/ Hex Artifact Content
Login

Artifact 82cfca85be9454f60a8be91e362ef3835dd895a2:


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 33 31 20 32 30 30 39 2f 30  n,v 1.431 2009/0
05f0: 32 2f 31 31 20 31 35 3a 32 33 3a 33 35 20 64 72  2/11 15:23:35 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20  .** These no-op 
0750: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
0760: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65  in front of inte
0770: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74  rfaces to mark t
0780: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hose.** interfac
0790: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70  es as either dep
07a0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72  recated or exper
07b0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70  imental.  New ap
07c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
07d0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70  ould not use dep
07e0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65  recated intrface
07f0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
0800: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72  port for backwar
0810: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
0820: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
0830: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
0840: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
0850: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
0860: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
0870: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0880: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0890: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
08a0: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
08b0: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
08c0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
08d0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
08e0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
08f0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0900: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0910: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
0920: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
0930: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
0940: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
0950: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
0960: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
0970: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0980: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0990: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
09a0: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
09b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
09c0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
09d0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
09e0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
09f0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a00: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a10: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0a20: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0a30: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0a40: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0a50: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0a60: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0a70: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0a80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0a90: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0aa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0ab0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0ac0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0ad0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0ae0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31  n Numbers {H1001
0af0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
0b00: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0b10: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f  SION and SQLITE_
0b20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23  VERSION_NUMBER #
0b30: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68  defines in.** th
0b40: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65  e sqlite3.h file
0b50: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72   specify the ver
0b60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77  sion of SQLite w
0b70: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61  ith which.** tha
0b80: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73  t header file is
0b90: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a   associated..**.
0ba0: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22  ** The "version"
0bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20   of SQLite is a 
0bc0: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f  string of the fo
0bd0: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54  rm "X.Y.Z"..** T
0be0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61  he phrase "alpha
0bf0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68  " or "beta" migh
0c00: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66  t be appended af
0c10: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68  ter the Z..** Th
0c20: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a  e X value is maj
0c30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0c40: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51  r always 3 in SQ
0c50: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20  Lite3..** The X 
0c60: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0c70: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64  es when backward
0c80: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
0c90: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64  is.** broken and
0ca0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65   we intend to ne
0cb0: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61  ver break backwa
0cc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0cd0: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75  y..** The Y valu
0ce0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  e is the minor v
0cf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
0d00: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  d only changes w
0d10: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65  hen.** there are
0d20: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65   major feature e
0d30: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74  nhancements that
0d40: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f   are forwards co
0d50: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20  mpatible.** but 
0d60: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f  not backwards co
0d70: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  mpatible..** The
0d80: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20   Z value is the 
0d90: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61  release number a
0da0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  nd is incremente
0db0: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0dc0: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0dd0: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0de0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d  ever Y is increm
0df0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ented..**.** See
0e00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
0e10: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  libversion()] an
0e20: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  d [sqlite3_libve
0e30: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e  rsion_number()].
0e40: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
0e50: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31  S:.**.** {H10011
0e60: 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  } The SQLITE_VER
0e70: 53 49 4f 4e 20 23 64 65 66 69 6e 65 20 69 6e 20  SION #define in 
0e80: 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65  the sqlite3.h he
0e90: 61 64 65 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a  ader file shall.
0ea0: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 76 61 6c  **          eval
0eb0: 75 61 74 65 20 74 6f 20 61 20 73 74 72 69 6e 67  uate to a string
0ec0: 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73   literal that is
0ed0: 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73   the SQLite vers
0ee0: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
0ef0: 77 69 74 68 20 77 68 69 63 68 20 74 68 65 20 68  with which the h
0f00: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73  eader file is as
0f10: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  sociated..**.** 
0f20: 7b 48 31 30 30 31 34 7d 20 54 68 65 20 53 51 4c  {H10014} The SQL
0f30: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0f40: 45 52 20 23 64 65 66 69 6e 65 20 73 68 61 6c 6c  ER #define shall
0f50: 20 72 65 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69   resolve to an i
0f60: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
0f70: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75     with the valu
0f80: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0f90: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0fa0: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20   X, Y, and Z.** 
0fb0: 20 20 20 20 20 20 20 20 20 61 72 65 20 74 68 65           are the
0fc0: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20   major version, 
0fd0: 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61  minor version, a
0fe0: 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  nd release numbe
0ff0: 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  r..*/.#define SQ
1000: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1010: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
1020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1030: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d  ERSION_NUMBER  -
1040: 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d  -VERSION-NUMBER-
1050: 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  -../*.** CAPI3RE
1060: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
1070: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
1080: 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c 53 36  ers {H10020} <S6
1090: 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0100>.** KEYWORD
10a0: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
10b0: 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  on.**.** These f
10c0: 65 61 74 75 72 65 73 20 70 72 6f 76 69 64 65 20  eatures provide 
10d0: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
10e0: 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c  tion as the [SQL
10f0: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20  ITE_VERSION].** 
1100: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  and [SQLITE_VERS
1110: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66  ION_NUMBER] #def
1120: 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61 64  ines in the head
1130: 65 72 2c 20 62 75 74 20 61 72 65 20 61 73 73 6f  er, but are asso
1140: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
1150: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1160: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
1170: 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75 73   file.  Cautious
1180: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
1190: 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20  ht.** include a 
11a0: 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72 20 61  check in their a
11b0: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 76 65  pplication to ve
11c0: 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c  rify that.** sql
11d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
11e0: 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 73 20  number() always 
11f0: 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1200: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  e.** [SQLITE_VER
1210: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a  SION_NUMBER]..**
1220: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1230: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1240: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1250: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1260: 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74  on as is.** in t
1270: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
1280: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1290: 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e 63 74  tant.  The funct
12a0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 0a  ion is provided.
12b0: 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c  ** for use in DL
12c0: 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65  Ls since DLL use
12d0: 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f  rs usually do no
12e0: 74 20 68 61 76 65 20 64 69 72 65 63 74 20 61 63  t have direct ac
12f0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a  cess to string.*
1300: 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68  * constants with
1310: 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a  in the DLL..**.*
1320: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1330: 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54 68 65  .** {H10021} The
1340: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
1350: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69  sion_number()] i
1360: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72  nterface shall r
1370: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
1380: 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75    an integer equ
1390: 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45  al to [SQLITE_VE
13a0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a  RSION_NUMBER]..*
13b0: 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20 54 68  *.** {H10022} Th
13c0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69  e [sqlite3_versi
13d0: 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  on] string const
13e0: 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69  ant shall contai
13f0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
1400: 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 5b 53  e text of the [S
1410: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73  QLITE_VERSION] s
1420: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
1430: 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  0023} The [sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d  e3_libversion()]
1450: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
1460: 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
1470: 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20     a pointer to 
1480: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72  the [sqlite3_ver
1490: 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e  sion] string con
14a0: 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  stant..*/.SQLITE
14b0: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
14c0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
14d0: 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72  on[];.const char
14e0: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
14f0: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  sion(void);.int 
1500: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1510: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
1520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1530: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1540: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1550: 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 30 31  Threadsafe {H101
1560: 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a  00} <S60100>.**.
1570: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1580: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1590: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
15a0: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
15b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
15c0: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
15d0: 6f 72 20 6d 61 63 72 6f 20 31 20 6f 72 20 32 2c  or macro 1 or 2,
15e0: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
15f0: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1600: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1610: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1620: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1630: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1640: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1650: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1660: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1670: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1680: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1690: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
16a0: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
16b0: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
16c0: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
16d0: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
16e0: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
16f0: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1700: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1710: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1720: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1730: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1740: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1750: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1760: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1770: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1780: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  ** The default b
1790: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
17a0: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
17b0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
17c0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
17d0: 65 20 75 73 65 64 20 62 79 20 61 20 70 72 6f 67  e used by a prog
17e0: 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ram to make sure
17f0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72   that the.** ver
1800: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74  sion of SQLite t
1810: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e  hat it is linkin
1820: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f  g against was co
1830: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
1840: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69  he desired setti
1850: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ng of the [SQLIT
1860: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1870: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cro..**.** This 
1880: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
1890: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f  eports on the co
18a0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78  mpile-time mutex
18b0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74   setting.** of t
18c0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
18d0: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66  DSAFE] flag.  If
18e0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
18f0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49  led with.** SQLI
1900: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20  TE_THREADSAFE=1 
1910: 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65  then mutexes are
1920: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
1930: 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62  ult but.** can b
1940: 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69  e fully or parti
1950: 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73  ally disabled us
1960: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
1970: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
1980: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72  .** with the ver
1990: 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  bs [SQLITE_CONFI
19a0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c  G_SINGLETHREAD],
19b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
19c0: 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a  MULTITHREAD],.**
19d0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
19e0: 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20  IG_MUTEX].  The 
19f0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
1a00: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
1a10: 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20  ows.** only the 
1a20: 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d  default compile-
1a30: 74 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f  time setting, no
1a40: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
1a50: 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61  hanges.** to tha
1a60: 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  t setting..**.**
1a70: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
1a80: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
1a90: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
1aa0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1ab0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  on..**.** INVARI
1ac0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ANTS:.**.** {H10
1ad0: 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  101} The [sqlite
1ae0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1af0: 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72  function shall r
1b00: 65 74 75 72 6e 20 7a 65 72 6f 20 69 66 0a 2a 2a  eturn zero if.**
1b10: 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6f 6e            and on
1b20: 6c 79 20 69 66 20 53 51 4c 69 74 65 20 77 61 73  ly if SQLite was
1b30: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1b40: 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69  utexing code omi
1b50: 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  tted..**.** {H10
1b60: 31 30 32 7d 20 54 68 65 20 76 61 6c 75 65 20 72  102} The value r
1b70: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 5b  eturned by the [
1b80: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1b90: 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  fe()] function.*
1ba0: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
1bb0: 20 72 65 6d 61 69 6e 20 74 68 65 20 73 61 6d 65   remain the same
1bc0: 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f   across calls to
1bd0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
1be0: 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1bf0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76  te3_threadsafe(v
1c00: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
1c10: 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
1c20: 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c  Connection Handl
1c30: 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30 32  e {H12000} <S402
1c40: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1c50: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
1c60: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
1c70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
1c80: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
1c90: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
1ca0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
1cb0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1cc0: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
1cd0: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
1ce0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
1cf0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
1d00: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
1d10: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
1d20: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
1d30: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
1d40: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1d50: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1d60: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
1d70: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
1d80: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
1d90: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
1da0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
1db0: 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 75  ** is its destru
1dc0: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65  ctor.  There are
1dd0: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65   many other inte
1de0: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
1df0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1e00: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
1e10: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1e20: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
1e30: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1e40: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
1e50: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
1e60: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
1e70: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
1e80: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
1e90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
1ea0: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
1eb0: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
1ec0: 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b 48  Integer Types {H
1ed0: 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a  10200} <S10110>.
1ee0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
1ef0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
1f00: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
1f10: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
1f20: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
1f30: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
1f40: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
1f50: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
1f60: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
1f70: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
1f80: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
1f90: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
1fa0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
1fb0: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
1fc0: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
1fd0: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69  ferred type defi
1fe0: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nitions..** The 
1ff0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64  sqlite_int64 and
2000: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
2010: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74  ypes are support
2020: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
2030: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
2040: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e  y only..**.** IN
2050: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2060: 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b 73 71  {H10201} The [sq
2070: 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20  lite_int64] and 
2080: 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20  [sqlite3_int64] 
2090: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
20a0: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
20b0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
20c0: 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nteger..**.** {H
20d0: 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  10202} The [sqli
20e0: 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b  te_uint64] and [
20f0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d 20  sqlite3_uint64] 
2100: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
2110: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
2120: 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
2130: 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66   integer..*/.#if
2140: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2150: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
2160: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2170: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
2180: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2190: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
21a0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
21b0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
21c0: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
21d0: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
21e0: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
21f0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2200: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2210: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2220: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2230: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2240: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2250: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2260: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
2270: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2280: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
2290: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
22a0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
22b0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
22c0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
22d0: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
22e0: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
22f0: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2300: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2310: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2320: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2330: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2340: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2350: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
2360: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
2370: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
2380: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
2390: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
23a0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
23b0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
23c0: 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c  ction {H12010} <
23d0: 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a  S30100><S40200>.
23e0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
23f0: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2400: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2410: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2420: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
2430: 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65  s should [sqlite
2440: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2450: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2460: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2470: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2480: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2490: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
24a0: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
24b0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
24c0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
24d0: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
24e0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
24f0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20   object..** The 
2500: 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2510: 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  mt()] interface 
2520: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
2530: 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72  ocate all.** [pr
2540: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2550: 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  s] associated wi
2560: 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
2570: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64 65  onnection] if de
2580: 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61  sired..** Typica
2590: 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f  l code might loo
25a0: 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  k like this:.**.
25b0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
25c0: 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  pre>.** sqlite3_
25d0: 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20  stmt *pStmt;.** 
25e0: 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d 20  while( (pStmt = 
25f0: 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2600: 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a  t(db, 0))!=0 ){.
2610: 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c 69  ** &nbsp;   sqli
2620: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74  te3_finalize(pSt
2630: 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70  mt);.** }.** </p
2640: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
2650: 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  .**.** If [sqlit
2660: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69  e3_close()] is i
2670: 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74  nvoked while a t
2680: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
2690: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
26a0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
26b0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
26c0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ack..**.** INVAR
26d0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
26e0: 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 73 66  2011} A successf
26f0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2700: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68  te3_close(C)] sh
2710: 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 65 0a  all destroy the.
2720: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
2730: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2740: 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a  ] object C..**.*
2750: 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73 75 63  * {H12012} A suc
2760: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2770: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2780: 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  )] shall return 
2790: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a  SQLITE_OK..**.**
27a0: 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75 63 63   {H12013} A succ
27b0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
27c0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
27d0: 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 65 20  ] shall release 
27e0: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
27f0: 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 74 65  memory and syste
2800: 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f  m resources asso
2810: 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 61 74  ciated with [dat
2820: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2830: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e  ].**          C.
2840: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 7d 20  .**.** {H12014} 
2850: 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
2860: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20  e3_close(C)] on 
2870: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
2880: 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a  ection] C that.*
2890: 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 20 6f  *          has o
28a0: 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20  ne or more open 
28b0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28c0: 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c  ents] shall fail
28d0: 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
28e0: 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53    an [SQLITE_BUS
28f0: 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a  Y] error code..*
2900: 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 41 20  *.** {H12015} A 
2910: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2920: 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72 65  _close(C)] where
2930: 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   C is a NULL poi
2940: 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  nter shall.**   
2950: 20 20 20 20 20 20 20 62 65 20 61 20 68 61 72 6d         be a harm
2960: 6c 65 73 73 20 6e 6f 2d 6f 70 20 72 65 74 75 72  less no-op retur
2970: 6e 69 6e 67 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  ning SQLITE_OK..
2980: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 39 7d 20 57  **.** {H12019} W
2990: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  hen [sqlite3_clo
29a0: 73 65 28 43 29 5d 20 69 73 20 69 6e 76 6f 6b 65  se(C)] is invoke
29b0: 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65  d on a [database
29c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 0a 2a   connection] C.*
29d0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
29e0: 68 61 73 20 61 20 70 65 6e 64 69 6e 67 20 74 72  has a pending tr
29f0: 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 20 74  ansaction, the t
2a00: 72 61 6e 73 61 63 74 69 6f 6e 20 73 68 61 6c 6c  ransaction shall
2a10: 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   be.**          
2a20: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
2a30: 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
2a40: 2a 2a 0a 2a 2a 20 7b 41 31 32 30 31 36 7d 20 54  **.** {A12016} T
2a50: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74  he C parameter t
2a60: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
2a70: 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74  (C)] must be eit
2a80: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20  her a NULL.**   
2a90: 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 6f         pointer o
2aa0: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2ab0: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2ac0: 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  tained.**       
2ad0: 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33     from [sqlite3
2ae0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2af0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
2b00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2b10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2b20: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
2b30: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a  usly closed..*/.
2b40: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2b50: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2b60: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2b70: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2b80: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2b90: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2ba0: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2bb0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2bc0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2bd0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2be0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2bf0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2c00: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2c10: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2c20: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2c30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2c40: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2c50: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2c60: 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30  e {H12100} <S100
2c70: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
2c90: 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76  erface is a conv
2ca0: 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75  enient way of ru
2cb0: 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72  nning one or mor
2cc0: 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
2cd0: 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69  nts without havi
2ce0: 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f  ng to write a lo
2cf0: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68  t of C code.  Th
2d00: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a  e UTF-8 encoded.
2d10: 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
2d20: 73 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20  s are passed in 
2d30: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
2d40: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2d50: 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68  e3_exec()..** Th
2d60: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  e statements are
2d70: 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62   evaluated one b
2d80: 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68  y one until eith
2d90: 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a  er an error or.*
2da0: 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69  * an interrupt i
2db0: 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f  s encountered, o
2dc0: 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65  r until they are
2dd0: 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20   all done.  The 
2de0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  3rd parameter.**
2df0: 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20   is an optional 
2e00: 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73  callback that is
2e10: 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
2e20: 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e  r each row of an
2e30: 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c  y query.** resul
2e40: 74 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74  ts produced by t
2e50: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2e60: 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61  s.  The 5th para
2e70: 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72  meter tells wher
2e80: 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e  e.** to write an
2e90: 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73  y error messages
2ea0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f  ..**.** The erro
2eb0: 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64  r message passed
2ec0: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
2ed0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
2ee0: 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65  is held.** in me
2ef0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2f00: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2f10: 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64  oc()].  To avoid
2f20: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a   a memory leak,.
2f30: 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61  ** the calling a
2f40: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
2f50: 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  d call [sqlite3_
2f60: 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65  free()] on any e
2f70: 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
2f80: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68  returned through
2f90: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
2fa0: 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  er when it has f
2fb0: 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a  inished using.**
2fc0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
2fd0: 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ge..**.** If the
2fe0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
2ff0: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  n the 2nd parame
3000: 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  ter is NULL or a
3010: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a  n empty string.*
3020: 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f  * or a string co
3030: 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68  ntaining only wh
3040: 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d  itespace and com
3050: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53  ments, then no S
3060: 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  QL.** statements
3070: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
3080: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  nd the database 
3090: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a  is not changed..
30a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
30b0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
30c0: 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
30d0: 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a  d in terms of.**
30e0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30f0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3100: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
3110: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3120: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ()]..** The sqli
3130: 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69  te3_exec() routi
3140: 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20  ne does nothing 
3150: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
3160: 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64  that cannot be d
3170: 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  one.** by [sqlit
3180: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
3190: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
31a0: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
31b0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
31c0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
31d0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 31 7d 20 41  **.** {H12101} A
31e0: 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
31f0: 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
3200: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
3210: 45 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E)].**          
3220: 73 68 61 6c 6c 20 73 65 71 75 65 6e 74 69 61 6c  shall sequential
3230: 6c 79 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20  ly evaluate all 
3240: 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  of the UTF-8 enc
3250: 6f 64 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  oded,.**        
3260: 20 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61    semicolon-sepa
3270: 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
3280: 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
3290: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
32a0: 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 53          string S
32b0: 20 77 69 74 68 69 6e 20 74 68 65 20 63 6f 6e 74   within the cont
32c0: 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ext of the [data
32d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32e0: 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30   D..**.** {H1210
32f0: 32 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  2} If the S para
3300: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3310: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3320: 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a  )] is NULL then.
3330: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
3340: 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 69  actions of the i
3350: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62  nterface shall b
3360: 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 69 66  e the same as if
3370: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
3380: 20 53 20 70 61 72 61 6d 65 74 65 72 20 77 65 72   S parameter wer
3390: 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  e an empty strin
33a0: 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 34  g..**.** {H12104
33b0: 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
33c0: 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  ue of [sqlite3_e
33d0: 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20  xec()] shall be 
33e0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61  [SQLITE_OK] if a
33f0: 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ll.**          S
3400: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75  QL statements ru
3410: 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61  n successfully a
3420: 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  nd to completion
3430: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 35 7d  ..**.** {H12105}
3440: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
3450: 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78  e of [sqlite3_ex
3460: 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 61  ec()] shall be a
3470: 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
3480: 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d 7a 65            non-ze
3490: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
34a0: 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61 74 65  if any SQL state
34b0: 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  ment fails..**.*
34c0: 2a 20 7b 48 31 32 31 30 37 7d 20 49 66 20 6f 6e  * {H12107} If on
34d0: 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
34e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
34f0: 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74  handed to [sqlit
3500: 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20  e3_exec()].**   
3510: 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 72 65         return re
3520: 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20 33 72  sults and the 3r
3530: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
3540: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a  ot NULL, then.**
3550: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61            the ca
3560: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3570: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
3580: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 73   3rd parameter s
3590: 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20  hall be.**      
35a0: 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65      invoked once
35b0: 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66   for each row of
35c0: 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b   result..**.** {
35d0: 48 31 32 31 31 30 7d 20 49 66 20 74 68 65 20 63  H12110} If the c
35e0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
35f0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65  a non-zero value
3600: 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65   then [sqlite3_e
3610: 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  xec()].**       
3620: 20 20 20 73 68 61 6c 6c 20 61 62 6f 72 74 20 74     shall abort t
3630: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3640: 20 69 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79   it is currently
3650: 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20   evaluating,.** 
3660: 20 20 20 20 20 20 20 20 20 73 6b 69 70 20 61 6c           skip al
3670: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  l subsequent SQL
3680: 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64   statements, and
3690: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
36a0: 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ABORT]..**.** {H
36b0: 31 32 31 31 33 7d 20 54 68 65 20 5b 73 71 6c 69  12113} The [sqli
36c0: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74  te3_exec()] rout
36d0: 69 6e 65 20 73 68 61 6c 6c 20 70 61 73 73 20 69  ine shall pass i
36e0: 74 73 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  ts 4th parameter
36f0: 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20 20 20   through.**     
3700: 20 20 20 20 20 61 73 20 74 68 65 20 31 73 74 20       as the 1st 
3710: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
3720: 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
3730: 20 7b 48 31 32 31 31 36 7d 20 54 68 65 20 5b 73   {H12116} The [s
3740: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
3750: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74  outine shall set
3760: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3770: 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20  er of its.**    
3780: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74        callback t
3790: 6f 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  o be the number 
37a0: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
37b0: 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
37c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
37d0: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ult..**.** {H121
37e0: 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
37f0: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65  _exec()] routine
3800: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 33   shall set the 3
3810: 72 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  rd parameter of 
3820: 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
3830: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61  callback to be a
3840: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3850: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68  ers to strings h
3860: 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  olding the.**   
3870: 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 66 6f         values fo
3880: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e  r each column in
3890: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73   the current res
38a0: 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73 0a 2a  ult set row as.*
38b0: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69  *          obtai
38c0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
38d0: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
38e0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 32 7d  ..**.** {H12122}
38f0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
3900: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  ec()] routine sh
3910: 61 6c 6c 20 73 65 74 20 74 68 65 20 34 74 68 20  all set the 4th 
3920: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73  parameter of its
3930: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
3940: 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61  lback to be an a
3950: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3960: 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64   to strings hold
3970: 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ing the.**      
3980: 20 20 20 20 6e 61 6d 65 73 20 6f 66 20 72 65 73      names of res
3990: 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f  ult columns as o
39a0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
39b0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
39c0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  e()]..**.** {H12
39d0: 31 32 35 7d 20 49 66 20 74 68 65 20 33 72 64 20  125} If the 3rd 
39e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
39f0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
3a00: 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20   NULL then.**   
3a10: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
3a20: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 69  exec()] shall si
3a30: 6c 65 6e 74 6c 79 20 64 69 73 63 61 72 64 20 71  lently discard q
3a40: 75 65 72 79 20 72 65 73 75 6c 74 73 2e 0a 2a 2a  uery results..**
3a50: 0a 2a 2a 20 7b 48 31 32 31 33 31 7d 20 49 66 20  .** {H12131} If 
3a60: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
3a70: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72  while parsing or
3a80: 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20   evaluating any 
3a90: 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20  of the SQL.**   
3aa0: 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
3ab0: 73 20 69 6e 20 74 68 65 20 53 20 70 61 72 61 6d  s in the S param
3ac0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
3ad0: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3ae0: 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20  ] and if.**     
3af0: 20 20 20 20 20 74 68 65 20 45 20 70 61 72 61 6d       the E param
3b00: 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  eter is not NULL
3b10: 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  , then [sqlite3_
3b20: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 74  exec()] shall st
3b30: 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
3b40: 69 6e 20 2a 45 20 61 6e 20 61 70 70 72 6f 70 72  in *E an appropr
3b50: 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
3b60: 67 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ge written into 
3b70: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a  memory obtained.
3b80: 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
3b90: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
3ba0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ()]..**.** {H121
3bb0: 33 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  34} The [sqlite3
3bc0: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3bd0: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
3be0: 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66  set the value of
3bf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 45 20  .**          *E 
3c00: 74 6f 20 4e 55 4c 4c 20 69 66 20 45 20 69 73 20  to NULL if E is 
3c10: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65  not NULL and the
3c20: 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73  re are no errors
3c30: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 37 7d  ..**.** {H12137}
3c40: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
3c50: 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66  ec(D,S,C,A,E)] f
3c60: 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65  unction shall se
3c70: 74 20 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64  t the [error cod
3c80: 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  e].**          a
3c90: 6e 64 20 6d 65 73 73 61 67 65 20 61 63 63 65 73  nd message acces
3ca0: 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74  sible via [sqlit
3cb0: 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 0a  e3_errcode()], .
3cc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3cd0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
3ce0: 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20  rcode()],.**    
3cf0: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
3d00: 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73  rrmsg()], and [s
3d10: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
3d20: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33  )]..**.** {H1213
3d30: 38 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  8} If the S para
3d40: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3d50: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3d60: 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  )] is NULL or an
3d70: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6d 70  .**          emp
3d80: 74 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e  ty string or con
3d90: 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74  tains nothing ot
3da0: 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70  her than whitesp
3db0: 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a  ace, comments,.*
3dc0: 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 2f 6f  *          and/o
3dd0: 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68  r semicolons, th
3de0: 65 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73  en results of [s
3df0: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
3e00: 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
3e10: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
3e20: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
3e30: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3e40: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
3e50: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3e60: 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
3e70: 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 74 6f    shall reset to
3e80: 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72 72   indicate no err
3e90: 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ors..**.** ASSUM
3ea0: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
3eb0: 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73 74  12141} The first
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
3ed0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6d  qlite3_exec()] m
3ee0: 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 20  ust be an valid 
3ef0: 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 20  and open.**     
3f00: 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
3f10: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
3f20: 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 20 64  * {A12142} The d
3f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3f40: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63  on must not be c
3f50: 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 20  losed while.**  
3f60: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
3f70: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
3f80: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31  ing..**.** {A121
3f90: 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  43} The calling 
3fa0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
3fb0: 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  use [sqlite3_fre
3fc0: 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20  e()] to free.** 
3fd0: 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d           the mem
3fe0: 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67  ory that *errmsg
3ff0: 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
4000: 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72  g at once the er
4010: 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ror.**          
4020: 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c 6f  message is no lo
4030: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a  nger needed..**.
4040: 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 65 20  ** {A12145} The 
4050: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
4060: 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61  xt in the 2nd pa
4070: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
4080: 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20  te3_exec()].**  
4090: 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 65 6d          must rem
40a0: 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77 68  ain unchanged wh
40b0: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ile [sqlite3_exe
40c0: 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  c()] is running.
40d0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
40e0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
40f0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4120: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4130: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4150: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4160: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4170: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4180: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4190: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
41a0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
41b0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
41c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
41f0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4200: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4210: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4230: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4240: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4250: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4260: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31  Result Codes {H1
4270: 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  0210} <S10700>.*
4280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4290: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
42a0: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
42b0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
42c0: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
42d0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
42e0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
42f0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
4300: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
4310: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
4320: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
4330: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4340: 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72  cates success or
4350: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
4360: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
4370: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
4380: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
4390: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
43a0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
43b0: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
43c0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
43d0: 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  codes].*/.#defin
43e0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
43f0: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4400: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4410: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4420: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4440: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4450: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
4460: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
4470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4480: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
4490: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
44a0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
44b0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
44c0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
44d0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
44e0: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
44f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4500: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4510: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4520: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4530: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4550: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4560: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4570: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
4580: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4590: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
45a0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
45b0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
45c0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
45d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
45e0: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
45f0: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4600: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4610: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4620: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4630: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4640: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4660: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4670: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
4680: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
4690: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
46a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46b0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
46c0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
46d0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
46e0: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
46f0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4700: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4710: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4720: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4730: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4740: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4750: 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53    12   /* NOT US
4760: 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63  ED. Table or rec
4770: 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f  ord not found */
4780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4790: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
47a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
47b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
47c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
47d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
47f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4800: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4810: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4820: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
4830: 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55     15   /* NOT U
4840: 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f  SED. Database lo
4850: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f  ck protocol erro
4860: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4870: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20  ITE_EMPTY       
4880: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  16   /* Database
4890: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65   is empty */.#de
48a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45  fine SQLITE_SCHE
48b0: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20  MA      17   /* 
48c0: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  The database sch
48d0: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23  ema changed */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f  define SQLITE_TO
48f0: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f  OBIG      18   /
4900: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  * String or BLOB
4910: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69   exceeds size li
4920: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mit */.#define S
4930: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
4940: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20    19   /* Abort 
4950: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e  due to constrain
4960: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23  t violation */.#
4970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4980: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f  SMATCH    20   /
4990: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d  * Data type mism
49a0: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20  atch */.#define 
49b0: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20  SQLITE_MISUSE   
49c0: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61     21   /* Libra
49d0: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63  ry used incorrec
49e0: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tly */.#define S
49f0: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20  QLITE_NOLFS     
4a00: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f    22   /* Uses O
4a10: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73  S features not s
4a20: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74  upported on host
4a30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a40: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32  TE_AUTH        2
4a50: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61  3   /* Authoriza
4a60: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  tion denied */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f  define SQLITE_FO
4a80: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f  RMAT      24   /
4a90: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61  * Auxiliary data
4aa0: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f  base format erro
4ab0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4ac0: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20  ITE_RANGE       
4ad0: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61  25   /* 2nd para
4ae0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4af0: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e  _bind out of ran
4b00: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge */.#define SQ
4b10: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20  LITE_NOTADB     
4b20: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70   26   /* File op
4b30: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74  ened that is not
4b40: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
4b50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b60: 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31  TE_ROW         1
4b70: 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  00  /* sqlite3_s
4b80: 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65  tep() has anothe
4b90: 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23  r row ready */.#
4ba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f  define SQLITE_DO
4bb0: 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f  NE        101  /
4bc0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
4bd0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
4be0: 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e  ecuting */./* en
4bf0: 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  d-of-error-codes
4c00: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
4c10: 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65  REF: Extended Re
4c20: 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30 32  sult Codes {H102
4c30: 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20  20} <S10700>.** 
4c40: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c50: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4c60: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4c70: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4c80: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c90: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4ca0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4cb0: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4cc0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4cd0: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4ce0: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4cf0: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4d00: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4d10: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4d20: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4d30: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4d40: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4d50: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4d60: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4d70: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4d80: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d90: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4da0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4db0: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4dc0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4dd0: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4de0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4df0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4e00: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4e10: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4e20: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4e30: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4e40: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4e50: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4e60: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4e70: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4e80: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e90: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4ea0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4eb0: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4ec0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4ed0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4ee0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4ef0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4f00: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4f10: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4f20: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4f30: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4f40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f50: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4f60: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4f70: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4f80: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f90: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4fa0: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4fb0: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4fc0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4fd0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4fe0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4ff0: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
5000: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
5010: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
5020: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
5030: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
5040: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
5050: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
5060: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
5070: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a  exactly zero..**
5080: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
5090: 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d 20 54  **.** {H10223} T
50a0: 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
50b0: 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64   for an extended
50c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68 61   result code sha
50d0: 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  ll contains.**  
50e0: 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74 65          a relate
50f0: 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74  d primary result
5100: 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 69   code as a prefi
5110: 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 34  x..**.** {H10224
5120: 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74  } Primary result
5130: 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c   code names shal
5140: 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67  l contain a sing
5150: 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72  le "_" character
5160: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 35 7d  ..**.** {H10225}
5170: 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   Extended result
5180: 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c   code names shal
5190: 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72  l contain two or
51a0: 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63   more "_" charac
51b0: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ters..**.** {H10
51c0: 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 63  226} The numeric
51d0: 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 74   value of an ext
51e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
51f0: 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20  e shall contain 
5200: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
5210: 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66  numeric value of
5220: 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64 69   its correspondi
5230: 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c  ng primary resul
5240: 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20 20  t code in.**    
5250: 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74 20        its least 
5260: 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62 69  significant 8 bi
5270: 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ts..*/.#define S
5280: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
5290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
52a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
52b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
52d0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
52e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
52f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5300: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
5310: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5320: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
5330: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5340: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
5350: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5360: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
5390: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
53b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53c0: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
53d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
53e0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
53f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5400: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
5410: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5420: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
5430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5440: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5450: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5460: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5480: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5490: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54a0: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
54b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54c0: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
54d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
54e0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
54f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5500: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
5510: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5520: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5540: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5560: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5580: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5590: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55a0: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
55b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55c0: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
55d0: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
55e0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
55f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5600: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
5610: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5620: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
5630: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5640: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5650: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5660: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5670: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5680: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5690: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
56a0: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 0a 2f  RR | (17<<8))../
56b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
56c0: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
56d0: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48  en Operations {H
56e0: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20  10230} <H11120> 
56f0: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12700>.**.** T
5700: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
5710: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
5720: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
5730: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
5740: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
5750: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
5760: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
5770: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
5780: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
5790: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
57a0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
57b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
57c0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
57d0: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
57e0: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
57f0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
5800: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
5810: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5820: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
5830: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5840: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
5850: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
5860: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
5870: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
5880: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
5890: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
58a0: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
58b0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
58c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
58d0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
58e0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
58f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5900: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
5910: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
5920: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
5930: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
5940: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
5950: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5960: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
5970: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
5980: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5990: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
59a0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
59b0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
59c0: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  2000.#define SQL
59d0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
59e0: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
59f0: 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  4000.#define SQL
5a00: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
5a10: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a20: 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  8000.#define SQL
5a30: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
5a40: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
5a50: 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0000../*.** CAPI
5a60: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5a70: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
5a80: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
5a90: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5aa0: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
5ab0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
5ac0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
5ad0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
5ae0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
5af0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5b00: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5b10: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5b20: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5b30: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5b40: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5b50: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5b60: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5b70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5b80: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5b90: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
5ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5bb0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
5bc0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
5bd0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
5be0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
5bf0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5c00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5c10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5c20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5c30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5c40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5c50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5c60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5c70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5c80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5c90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
5ca0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5cb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
5cc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
5cd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
5ce0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
5cf0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5d00: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5d10: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5d20: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5d30: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5d40: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5d50: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5d60: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5d70: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5d80: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5d90: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
5da0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
5db0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
5dc0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
5dd0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
5de0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5df0: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
5e00: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5e10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e20: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
5e30: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
5e40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e50: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
5e60: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
5e70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e80: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
5e90: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
5ea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5eb0: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
5ec0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5ed0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ee0: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
5ef0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
5f00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f10: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
5f20: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
5f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f40: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
5f50: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
5f60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f70: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
5f80: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
5f90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5fa0: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
5fb0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
5fc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
5fd0: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
5fe0: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
5ff0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6000: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
6010: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
6020: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
6030: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
6040: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6050: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6060: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
6070: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
6080: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
6090: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
60a0: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
60b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
60c0: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
60d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
60e0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
60f0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
6100: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
6110: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
6120: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6130: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
6140: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
6150: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
6160: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6170: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
6180: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
6190: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
61a0: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
61b0: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
61c0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
61d0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
61e0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
61f0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6200: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6210: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
6220: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
6230: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6240: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6250: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
6260: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
6270: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6280: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
6290: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
62a0: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
62b0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
62c0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
62d0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
62e0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
62f0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
6300: 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54  ushed. The SQLIT
6310: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c  E_SYNC_NORMAL fl
6320: 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  ag means.** to u
6330: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
6340: 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65  ) semantics. The
6350: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6360: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20  L flag means.** 
6370: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
6380: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
6390: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
63a0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
63b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
63c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
63d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
63e0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
63f0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
6400: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6410: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
6420: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
6430: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
6440: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
6450: 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30  le {H11110} <S20
6460: 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  110>.**.** An [s
6470: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6480: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
6490: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
64a0: 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61  he OS.** interfa
64b0: 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76  ce layer.  Indiv
64c0: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
64d0: 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ce implementatio
64e0: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
64f0: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
6500: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
6510: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
6520: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
6530: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
6540: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
6550: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
6560: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6570: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6580: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
6590: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
65a0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
65b0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
65c0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
65d0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
65e0: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
65f0: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
6600: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
6610: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
6620: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
6630: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
6640: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
6650: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
6660: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6670: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
6680: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
6690: 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30 7d   Object {H11120}
66a0: 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S20110>.**.** 
66b0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
66c0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
66d0: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74  3_vfs] xOpen met
66e0: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
66f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
6700: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
6710: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
6720: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
6730: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
6740: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
6750: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
6760: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
6770: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
6780: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
6790: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
67a0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
67b0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
67c0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
67d0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
67e0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
67f0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
6800: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
6810: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
6820: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
6830: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
6840: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
6850: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
6860: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
6870: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
6880: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
6890: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
68a0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
68b0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
68c0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
68d0: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
68e0: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
68f0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
6900: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
6910: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
6920: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
6930: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
6940: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
6950: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
6960: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6970: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
6980: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6990: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
69a0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
69b0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
69c0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
69d0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
69e0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
69f0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
6a00: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
6a10: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6a20: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
6a30: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
6a40: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
6a50: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
6a60: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
6a70: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
6a80: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
6a90: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
6aa0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
6ab0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
6ac0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
6ad0: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
6ae0: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
6af0: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
6b00: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
6b10: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
6b20: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
6b30: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
6b40: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
6b50: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
6b60: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
6b70: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
6b80: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
6b90: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
6ba0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
6bb0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
6bc0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
6bd0: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
6be0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
6bf0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
6c00: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
6c10: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
6c20: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
6c30: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
6c40: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
6c50: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
6c60: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
6c70: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
6c80: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
6c90: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
6ca0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
6cb0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
6cc0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
6cd0: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
6ce0: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
6cf0: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
6d00: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
6d10: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
6d20: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
6d30: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
6d40: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
6d50: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
6d60: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
6d70: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
6d80: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
6d90: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
6da0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
6db0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
6dc0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
6dd0: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
6de0: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
6df0: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
6e00: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
6e10: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
6e20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
6e30: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
6e40: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
6e50: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
6e60: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
6e70: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
6e80: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
6e90: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
6ea0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
6eb0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
6ec0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
6ed0: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nflicts..**.** T
6ee0: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
6ef0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6f00: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
6f10: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
6f20: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
6f30: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
6f40: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
6f50: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
6f60: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
6f70: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
6f80: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
6f90: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
6fa0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
6fb0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6fc0: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
6fd0: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
6fe0: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
6ff0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
7000: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
7010: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
7020: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7030: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
7040: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7050: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
7060: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7070: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
7080: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7090: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
70a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
70c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
70e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
7100: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7110: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
7120: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7130: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
7140: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7150: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
7160: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
7170: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
7180: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
7190: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
71a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
71b0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
71c0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
71d0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
71e0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
71f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7200: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
7210: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
7220: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
7230: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
7240: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
7250: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
7260: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
7270: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
7280: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
7290: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
72a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
72b0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
72c0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
72d0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
72e0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
72f0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
7300: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
7310: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
7320: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
7330: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
7340: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
7350: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
7360: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
7370: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
7380: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
7390: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
73a0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
73b0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
73c0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
73d0: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
73e0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
73f0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
7400: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
7410: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
7420: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
7430: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
7440: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
7450: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
7460: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
7470: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
7480: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
7490: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
74a0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
74b0: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
74c0: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
74d0: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
74e0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
74f0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7500: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
7510: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
7520: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
7530: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
7540: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
7550: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
7560: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7570: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
7580: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
7590: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
75a0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
75b0: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
75c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
75d0: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
75e0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
75f0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
7600: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
7610: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
7620: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
7630: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
7640: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7650: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
7660: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
7670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
7680: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
7690: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
76a0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
76b0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
76c0: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
76d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
76e0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
76f0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
7700: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
7710: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
7720: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
7730: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7740: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
7750: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
7760: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
7770: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
7780: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
7790: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
77a0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64  _file*);.  /* Ad
77b0: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
77c0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
77d0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
77e0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
77f0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
7800: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
7810: 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d 20 3c  codes {H11310} <
7820: 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30800>.**.** Th
7830: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
7840: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
7850: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
7860: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
7870: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
7880: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7890: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
78a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
78b0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
78c0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
78d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
78e0: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
78f0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
7900: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
7910: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
7920: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
7930: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
7940: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
7950: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
7960: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
7970: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
7980: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7990: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
79a0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
79b0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
79c0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
79d0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
79e0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
79f0: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
7a00: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
7a10: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
7a20: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
7a30: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
7a40: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
7a50: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
7a60: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
7a70: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
7a80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7a90: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
7aa0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
7ab0: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
7ac0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
7ad0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7ae0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
7af0: 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  LE      3.#defin
7b00: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
7b10: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
7b20: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
7b30: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20  F: Mutex Handle 
7b40: 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31 33 30  {H17110} <S20130
7b50: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  >.**.** The mute
7b60: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
7b70: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
7b80: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
7b90: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
7ba0: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
7bb0: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
7bc0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
7bd0: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
7be0: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
7bf0: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
7c00: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
7c10: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
7c20: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
7c30: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
7c40: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
7c50: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
7c60: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
7c70: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
7c80: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
7c90: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7ca0: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
7cb0: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
7cc0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7cd0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b  terface Object {
7ce0: 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30 30 3e  H11140} <S20100>
7cf0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
7d00: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
7d10: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
7d20: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
7d30: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
7d40: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
7d50: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
7d60: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7d70: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
7d80: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
7d90: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
7da0: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
7db0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a  ile system"..**.
7dc0: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
7dd0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
7de0: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
7df0: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
7e00: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
7e10: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
7e20: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
7e30: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
7e40: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
7e50: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
7e60: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
7e70: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
7e80: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
7e90: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
7ea0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
7eb0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
7ec0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
7ed0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
7ee0: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
7ef0: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
7f00: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
7f10: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
7f20: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
7f30: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
7f40: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
7f50: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
7f60: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
7f70: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
7f80: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
7f90: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
7fa0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
7fb0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
7fc0: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
7fd0: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
7fe0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
7ff0: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
8000: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
8010: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
8020: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
8030: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
8040: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
8050: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
8060: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
8070: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
8080: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
8090: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
80a0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
80b0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
80c0: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
80d0: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
80e0: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
80f0: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
8100: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
8110: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
8120: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
8130: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
8140: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
8150: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
8160: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
8170: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
8180: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
8190: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
81a0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
81b0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
81c0: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
81d0: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
81e0: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
81f0: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
8200: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
8210: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
8220: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
8230: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
8240: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
8250: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
8260: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
8270: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
8280: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
8290: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
82a0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
82b0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
82c0: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
82d0: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
82e0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72  SQLite will guar
82f0: 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 7a  antee that the z
8300: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
8310: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
8320: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
8330: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
8340: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
8350: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
8360: 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72 74  ().  SQLite furt
8370: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
8380: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
8390: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
83a0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
83b0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
83c0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
83d0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
83e0: 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a 2a 20  us sentense,.** 
83f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8400: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
8410: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
8420: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
8430: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
8440: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
8450: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
8460: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
8470: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
8480: 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 69 73  eter is xOpen is
8490: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
84a0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
84b0: 73 74 20 69 6e 76 69 74 65 20 69 74 73 20 6f 77  st invite its ow
84c0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
84d0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
84e0: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
84f0: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
8500: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
8510: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
8520: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
8530: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
8540: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
8550: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8560: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
8570: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
8580: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
8590: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
85a0: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
85b0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
85c0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
85d0: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
85e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
85f0: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
8600: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
8610: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
8620: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
8630: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
8640: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
8650: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
8660: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
8670: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
8680: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
8690: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
86a0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
86b0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
86c0: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
86d0: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
86e0: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
86f0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73   SQLite will als
8700: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
8710: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
8720: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
8730: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
8740: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
8750: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
8760: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8770: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8780: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
8790: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
87a0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
87b0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
87c0: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
87d0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
87e0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
87f0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8800: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
8810: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
8820: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
8830: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
8840: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
8850: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
8860: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  /ul>.**.** The f
8870: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
8880: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
8890: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
88a0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
88b0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
88c0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
88d0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
88e0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
88f0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
8900: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
8910: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
8920: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
8930: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
8940: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
8950: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
8960: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
8970: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
8980: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
8990: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
89a0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
89b0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
89c0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
89d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
89e0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
89f0: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
8a00: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
8a10: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
8a20: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
8a30: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
8a40: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
8a50: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
8a60: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
8a70: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
8a80: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
8a90: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
8aa0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
8ab0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
8ac0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
8ad0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8ae0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8af0: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
8b00: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8b10: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
8b20: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
8b30: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8b40: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
8b50: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8b60: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
8b70: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
8b80: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8b90: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
8ba0: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
8bb0: 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73  or TEMP  databas
8bc0: 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64  es, journals and
8bd0: 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73   for subjournals
8be0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
8bf0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8c00: 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  VE] flag means t
8c10: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
8c20: 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20  e opened.** for 
8c30: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8c40: 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 73 20  .  This flag is 
8c50: 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65  set for all file
8c60: 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20  s except.** for 
8c70: 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
8c80: 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 74  e file..**.** At
8c90: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
8ca0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
8cb0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
8cc0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
8cd0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
8ce0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
8cf0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
8d00: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
8d10: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
8d20: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
8d30: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
8d40: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
8d50: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
8d60: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
8d70: 69 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  in..**.** The fl
8d80: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
8d90: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
8da0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
8db0: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
8dc0: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
8dd0: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
8de0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8df0: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
8e00: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
8e10: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
8e20: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
8e30: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
8e40: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
8e50: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
8e60: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
8e70: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
8e80: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
8e90: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
8ea0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
8eb0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
8ec0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
8ed0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
8ee0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
8ef0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
8f00: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
8f10: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
8f20: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
8f30: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
8f40: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
8f50: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
8f60: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
8f70: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
8f80: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
8f90: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
8fa0: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
8fb0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
8fc0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
8fd0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
8fe0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
8ff0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
9000: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
9010: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
9020: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
9030: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
9040: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
9050: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
9060: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
9070: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
9080: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
9090: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c   are not strictl
90a0: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20  y a part of the 
90b0: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20  filesystem, but 
90c0: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c  they are.** incl
90d0: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20  uded in the VFS 
90e0: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f  structure for co
90f0: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54  mpleteness..** T
9100: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
9110: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70   function attemp
9120: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79  ts to return nBy
9130: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  tes bytes.** of 
9140: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e  good-quality ran
9150: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75  domness into zOu
9160: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  t.  The return v
9170: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61  alue is.** the a
9180: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  ctual number of 
9190: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
91a0: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a  ess obtained..**
91b0: 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   The xSleep() me
91c0: 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20  thod causes the 
91d0: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74  calling thread t
91e0: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a  o sleep for at.*
91f0: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  * least the numb
9200: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e  er of microsecon
9210: 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78  ds given.  The x
9220: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
9230: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
9240: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
9250: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
9260: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
9270: 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66  e..**.*/.typedef
9280: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
9290: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
92a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
92b0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
92c0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
92d0: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
92e0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  rsion number */.
92f0: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
9300: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
9310: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
9320: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
9330: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
9340: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
9350: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
9360: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
9370: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
9380: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
9390: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
93a0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
93b0: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
93c0: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
93d0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
93e0: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
93f0: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
9400: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
9410: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
9420: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
9430: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
9440: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
9450: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
9460: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
9470: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
9480: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
9490: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
94a0: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
94b0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
94c0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
94d0: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
94e0: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
94f0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
9500: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
9510: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
9520: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
9530: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
9540: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
9550: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
9560: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
9570: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
9580: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
9590: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
95a0: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
95b0: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
95c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
95d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
95e0: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28  Msg);.  void (*(
95f0: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
9600: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
9610: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
9620: 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64  ))(void);.  void
9630: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
9640: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
9650: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
9660: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
9670: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
9680: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
9690: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
96a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
96b0: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
96c0: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
96d0: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
96e0: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69  *, double*);.  i
96f0: 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72  nt (*xGetLastErr
9700: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
9710: 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a  , int, char *);.
9720: 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    /* New fields 
9730: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
9740: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
9750: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
9760: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
9770: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
9780: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
9790: 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  s. */.};../*.** 
97a0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
97b0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
97c0: 56 46 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 31  VFS method {H111
97d0: 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a  90} <H11140>.**.
97e0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
97f0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
9800: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
9810: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
9820: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
9830: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
9840: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
9850: 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64  t. {END}  They d
9860: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
9870: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
9880: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
9890: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
98a0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
98b0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
98c0: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
98d0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
98e0: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
98f0: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
9900: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
9910: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
9920: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
9930: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
9940: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
9950: 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  e is both readab
9960: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e  le and writable.
9970: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
9980: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
9990: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
99a0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
99b0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
99c0: 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69  adable..*/.#defi
99d0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
99e0: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
99f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
9a00: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23  SS_READWRITE 1.#
9a10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
9a20: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
9a30: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9a40: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
9a50: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20   SQLite Library 
9a60: 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30  {H10130} <S20000
9a70: 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S30100>.**.** 
9a80: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9a90: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9aa0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
9ab0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
9ac0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
9ad0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
9ae0: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
9af0: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
9b00: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
9b10: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
9b20: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
9b30: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
9b40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9b50: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
9b60: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
9b70: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
9b80: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
9b90: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
9ba0: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
9bb0: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
9bc0: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
9bd0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
9be0: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
9bf0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
9c00: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
9c10: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
9c20: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9c30: 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63  .  Only an effec
9c40: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
9c50: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9c60: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
9c70: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
9c80: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
9c90: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
9ca0: 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  o-ops..**.** Amo
9cb0: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
9cc0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9cd0: 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f  ize() shall invo
9ce0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
9cf0: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
9d00: 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75  rly, sqlite3_shu
9d10: 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c  tdown().** shall
9d20: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
9d30: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
9d40: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9d50: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9d60: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
9d70: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
9d80: 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20  .** If for some 
9d90: 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  reason, sqlite3_
9da0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
9db0: 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61  unable to initia
9dc0: 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72  lize.** the libr
9dd0: 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20  ary (perhaps it 
9de0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
9df0: 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72  ocate a needed r
9e00: 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20  esource such.** 
9e10: 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72  as a mutex) it r
9e20: 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72  eturns an [error
9e30: 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61   code] other tha
9e40: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  n [SQLITE_OK]..*
9e50: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
9e60: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
9e70: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
9e80: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
9e90: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
9ea0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
9eb0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
9ec0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
9ed0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
9ee0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
9ef0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
9f00: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
9f10: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
9f20: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
9f30: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9f40: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
9f50: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
9f60: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
9f70: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
9f80: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
9f90: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
9fa0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
9fb0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
9fc0: 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76 65 72  lready.  However
9fd0: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
9fe0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
9ff0: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
a000: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
a010: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
a020: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
a030: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
a040: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a050: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
a060: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
a070: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
a080: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a090: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
a0a0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
a0b0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
a0c0: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
a0d0: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
a0e0: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
a0f0: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
a100: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
a110: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
a120: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
a130: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
a140: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
a150: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a160: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
a170: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
a180: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
a190: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
a1a0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
a1b0: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
a1c0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
a1d0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
a1e0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
a1f0: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
a200: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
a210: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
a220: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
a230: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
a240: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
a250: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
a260: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
a270: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
a280: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
a290: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
a2a0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
a2b0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
a2c0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
a2d0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
a2e0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
a2f0: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
a300: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
a310: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
a320: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
a330: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
a340: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
a350: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
a360: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
a370: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
a380: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
a390: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
a3a0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
a3b0: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
a3c0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
a3d0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
a3e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
a3f0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
a400: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
a410: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
a420: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a430: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
a440: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
a450: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
a460: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
a470: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
a480: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
a490: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
a4a0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
a4b0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
a4c0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
a4d0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
a4e0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
a4f0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
a500: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a510: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
a520: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a530: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
a540: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a550: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
a560: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
a570: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
a580: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
a590: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
a5a0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75  s compiled for u
a5b0: 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72  nix, windows, or
a5c0: 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62   os/2..** When b
a5d0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
a5e0: 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20  latforms (using 
a5f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
a600: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
a610: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
a620: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
a630: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
a640: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
a650: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
a660: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
a670: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
a680: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
a690: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
a6a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a6b0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
a6c0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
a6d0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
a6e0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
a6f0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
a700: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
a710: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
a720: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
a730: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
a740: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
a750: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
a760: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
a770: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
a780: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
a790: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
a7a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
a7b0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
a7c0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48  QLite Library {H
a7d0: 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c  14100} <S20000><
a7e0: 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S30200>.** EXPER
a7f0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
a800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
a810: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
a820: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
a830: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
a840: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
a850: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
a860: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
a870: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
a880: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
a890: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
a8a0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
a8b0: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
a8c0: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
a8d0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
a8e0: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
a8f0: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
a900: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
a910: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
a920: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
a930: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
a940: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
a950: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
a960: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
a970: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
a980: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
a990: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
a9a0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
a9b0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
a9c0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
a9d0: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
a9e0: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
a9f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
aa00: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
aa10: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
aa20: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
aa30: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
aa40: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
aa50: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
aa60: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
aa70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
aa80: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
aa90: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
aaa0: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
aab0: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
aac0: 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  hat sqlite3_conf
aad0: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
aae0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
aaf0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
ab00: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
ab10: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
ab20: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ab30: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
ab40: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
ab50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ab60: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
ab70: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
ab80: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
ab90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
aba0: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
abb0: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
abc0: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
abd0: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
abe0: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
abf0: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
ac00: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
ac10: 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
ac20: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
ac30: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
ac40: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
ac50: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ac60: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63  ..**.** When a c
ac70: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ac80: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
ac90: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
aca0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
acb0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69  ..** If the opti
acc0: 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
acd0: 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
ace0: 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
acf0: 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
ad00: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
ad10: 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
ad20: 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
ad30: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
ad40: 2a 20 7b 48 31 34 31 30 33 7d 20 41 20 73 75 63  * {H14103} A suc
ad50: 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
ad60: 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63  on of [sqlite3_c
ad70: 6f 6e 66 69 67 28 29 5d 20 73 68 61 6c 6c 20 72  onfig()] shall r
ad80: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
ad90: 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a    [SQLITE_OK]..*
ada0: 2a 0a 2a 2a 20 7b 48 31 34 31 30 36 7d 20 54 68  *.** {H14106} Th
adb0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
adc0: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  g()] interface s
add0: 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  hall return [SQL
ade0: 49 54 45 5f 4d 49 53 55 53 45 5d 0a 2a 2a 20 20  ITE_MISUSE].**  
adf0: 20 20 20 20 20 20 20 20 69 66 20 69 74 20 69 73          if it is
ae00: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 62 65 74 77   invoked in betw
ae10: 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  een calls to [sq
ae20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ae30: 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ()] and.**      
ae40: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 68 75      [sqlite3_shu
ae50: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  tdown()]..**.** 
ae60: 7b 48 31 34 31 32 30 7d 20 41 20 73 75 63 63 65  {H14120} A succe
ae70: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
ae80: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
ae90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
aea0: 4e 47 4c 45 54 48 52 45 41 44 5d 29 0a 2a 2a 20  NGLETHREAD]).** 
aeb0: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73           shall s
aec0: 65 74 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  et the default [
aed0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
aee0: 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
aef0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 33 7d  ..**.** {H14123}
af00: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
af10: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
af20: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
af30: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
af40: 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D]).**          
af50: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 64 65  shall set the de
af60: 66 61 75 6c 74 20 5b 74 68 72 65 61 64 69 6e 67  fault [threading
af70: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
af80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  thread..**.** {H
af90: 31 34 31 32 36 7d 20 41 20 73 75 63 63 65 73 73  14126} A success
afa0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
afb0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
afc0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
afd0: 41 4c 49 5a 45 44 5d 29 0a 2a 2a 20 20 20 20 20  ALIZED]).**     
afe0: 20 20 20 20 20 73 68 61 6c 6c 20 73 65 74 20 74       shall set t
aff0: 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68 72 65  he default [thre
b000: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
b010: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  erialized..**.**
b020: 20 7b 48 31 34 31 32 39 7d 20 41 20 73 75 63 63   {H14129} A succ
b030: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
b040: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
b050: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
b060: 55 54 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20  UTEX],X).**     
b070: 20 20 20 20 20 77 68 65 72 65 20 58 20 69 73 20       where X is 
b080: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
b090: 69 6e 69 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c  initialized [sql
b0a0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
b0b0: 64 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ds].**          
b0c0: 6f 62 6a 65 63 74 20 73 68 61 6c 6c 20 63 61 75  object shall cau
b0d0: 73 65 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  se all subsequen
b0e0: 74 20 6d 75 74 65 78 20 6f 70 65 72 61 74 69 6f  t mutex operatio
b0f0: 6e 73 20 70 65 72 66 6f 72 6d 65 64 0a 2a 2a 20  ns performed.** 
b100: 20 20 20 20 20 20 20 20 20 62 79 20 53 51 4c 69           by SQLi
b110: 74 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 75  te to use the mu
b120: 74 65 78 20 6d 65 74 68 6f 64 73 20 74 68 61 74  tex methods that
b130: 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 69 6e   were present in
b140: 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64   X.**          d
b150: 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 74  uring the call t
b160: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b170: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  g()]..**.** {H14
b180: 31 33 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  132} A successfu
b190: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
b1a0: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b1b0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
b1c0: 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 20 20  EX],X).**       
b1d0: 20 20 20 77 68 65 72 65 20 58 20 69 73 20 61 20     where X is a 
b1e0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73  pointer to an [s
b1f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
b200: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 0a 2a 2a  hods] object .**
b210: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
b220: 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 63 6f  overwrite the co
b230: 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65  ntent of [sqlite
b240: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
b250: 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20   object.**      
b260: 20 20 20 20 77 69 74 68 20 74 68 65 20 6d 75 74      with the mut
b270: 65 78 20 6d 65 74 68 6f 64 73 20 63 75 72 72 65  ex methods curre
b280: 6e 74 6c 79 20 69 6e 20 75 73 65 20 62 79 20 53  ntly in use by S
b290: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  QLite..**.** {H1
b2a0: 34 31 33 35 7d 20 41 20 73 75 63 63 65 73 73 66  4135} A successf
b2b0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
b2c0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
b2d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
b2e0: 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20 20 20 20 20  C],M).**        
b2f0: 20 20 77 68 65 72 65 20 4d 20 69 73 20 61 20 70    where M is a p
b300: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 69  ointer to an ini
b310: 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c 69 74 65  tialized [sqlite
b320: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
b330: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63  *          objec
b340: 74 20 73 68 61 6c 6c 20 63 61 75 73 65 20 61 6c  t shall cause al
b350: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6d 65 6d  l subsequent mem
b360: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ory allocation o
b370: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 20 20 20  perations.**    
b380: 20 20 20 20 20 20 70 65 72 66 6f 72 6d 65 64 20        performed 
b390: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  by SQLite to use
b3a0: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 74 68 61   the methods tha
b3b0: 74 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 69  t were present i
b3c0: 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d  n .**          M
b3d0: 20 64 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c   during the call
b3e0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
b3f0: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  fig()]..**.** {H
b400: 31 34 31 33 38 7d 20 41 20 73 75 63 63 65 73 73  14138} A success
b410: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
b420: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
b430: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
b440: 41 4c 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20  ALLOC],M).**    
b450: 20 20 20 20 20 20 77 68 65 72 65 20 4d 20 69 73        where M is
b460: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
b470: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
b480: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 73 68  thods] object sh
b490: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
b4a0: 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 63 6f  overwrite the co
b4b0: 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65  ntent of [sqlite
b4c0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 6f  3_mem_methods] o
b4d0: 62 6a 65 63 74 20 77 69 74 68 20 0a 2a 2a 20 20  bject with .**  
b4e0: 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d 6f          the memo
b4f0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6d 65  ry allocation me
b500: 74 68 6f 64 73 20 63 75 72 72 65 6e 74 6c 79 20  thods currently 
b510: 69 6e 20 75 73 65 20 62 79 0a 2a 2a 20 20 20 20  in use by.**    
b520: 20 20 20 20 20 20 53 51 4c 69 74 65 2e 0a 2a 2a        SQLite..**
b530: 0a 2a 2a 20 7b 48 31 34 31 34 31 7d 20 41 20 73  .** {H14141} A s
b540: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
b550: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b560: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
b570: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 31 29 0a  G_MEMSTATUS],1).
b580: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
b590: 6c 20 65 6e 61 62 6c 65 20 74 68 65 20 6d 65 6d  l enable the mem
b5a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
b5b0: 74 61 74 75 73 20 63 6f 6c 6c 65 63 74 69 6f 6e  tatus collection
b5c0: 20 6c 6f 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48   logic..**.** {H
b5d0: 31 34 31 34 34 7d 20 41 20 73 75 63 63 65 73 73  14144} A success
b5e0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
b5f0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
b600: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
b610: 54 41 54 55 53 5d 2c 30 29 0a 2a 2a 20 20 20 20  TATUS],0).**    
b620: 20 20 20 20 20 20 73 68 61 6c 6c 20 64 69 73 61        shall disa
b630: 62 6c 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ble the memory a
b640: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73  llocation status
b650: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69   collection logi
b660: 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 37  c..**.** {H14147
b670: 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  } The memory all
b680: 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63  ocation status c
b690: 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 20  ollection logic 
b6a0: 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20  shall be.**     
b6b0: 20 20 20 20 20 65 6e 61 62 6c 65 64 20 62 79 20       enabled by 
b6c0: 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b  default..**.** {
b6d0: 48 31 34 31 35 30 7d 20 41 20 73 75 63 63 65 73  H14150} A succes
b6e0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
b6f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
b700: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
b710: 41 54 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20  ATCH],S,Z,N).** 
b720: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a           where Z
b730: 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e   and N are non-n
b740: 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73  egative integers
b750: 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20   and .**        
b760: 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72    S is a pointer
b770: 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d   to an aligned m
b780: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74  emory buffer not
b790: 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20   less than.**   
b7a0: 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73         Z*N bytes
b7b0: 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63   in size shall c
b7c0: 61 75 73 65 20 53 20 74 6f 20 62 65 20 75 73 65  ause S to be use
b7d0: 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
b7e0: 20 20 20 20 20 5b 73 63 72 61 74 63 68 20 6d 65       [scratch me
b7f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
b800: 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73 20 4e  for as many as N
b810: 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73 0a 2a   simulataneous.*
b820: 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63  *          alloc
b830: 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66 20 73  ations each of s
b840: 69 7a 65 20 28 5a 20 26 20 7e 37 29 2e 0a 2a 2a  ize (Z & ~7)..**
b850: 0a 2a 2a 20 7b 48 31 34 31 35 33 7d 20 41 20 73  .** {H14153} A s
b860: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
b870: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b880: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
b890: 47 5f 53 43 52 41 54 43 48 5d 2c 53 2c 5a 2c 4e  G_SCRATCH],S,Z,N
b8a0: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  ).**          wh
b8b0: 65 72 65 20 53 20 69 73 20 61 20 4e 55 4c 4c 20  ere S is a NULL 
b8c0: 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 64 69  pointer shall di
b8d0: 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20 20 20  sable the.**    
b8e0: 20 20 20 20 20 20 5b 73 63 72 61 74 63 68 20 6d        [scratch m
b8f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
b900: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 36 7d  ..**.** {H14156}
b910: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
b920: 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ll to.**        
b930: 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69    [sqlite3_confi
b940: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
b950: 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 53 2c 5a  G_PAGECACHE],S,Z
b960: 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ,N).**          
b970: 77 68 65 72 65 20 5a 20 61 6e 64 20 4e 20 61 72  where Z and N ar
b980: 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 69  e non-negative i
b990: 6e 74 65 67 65 72 73 20 61 6e 64 20 0a 2a 2a 20  ntegers and .** 
b9a0: 20 20 20 20 20 20 20 20 20 53 20 69 73 20 61 20           S is a 
b9b0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 6c  pointer to an al
b9c0: 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
b9d0: 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 74 68 61  fer not less tha
b9e0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5a 2a  n.**          Z*
b9f0: 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
ba00: 73 68 61 6c 6c 20 63 61 75 73 65 20 53 20 74 6f  shall cause S to
ba10: 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65 0a   be used by the.
ba20: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 61 67  **          [pag
ba30: 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ecache memory al
ba40: 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 61 73 20  locator] for as 
ba50: 6d 61 6e 79 20 61 73 20 4e 20 73 69 6d 75 6c 61  many as N simula
ba60: 74 61 6e 65 6f 75 73 0a 2a 2a 20 20 20 20 20 20  taneous.**      
ba70: 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20      allocations 
ba80: 65 61 63 68 20 6f 66 20 73 69 7a 65 20 28 5a 20  each of size (Z 
ba90: 26 20 7e 37 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  & ~7)..**.** {H1
baa0: 34 31 35 39 7d 20 41 20 73 75 63 63 65 73 73 66  4159} A successf
bab0: 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20  ul call to.**   
bac0: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
bad0: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
bae0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
baf0: 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20  ],S,Z,N).**     
bb00: 20 20 20 20 20 77 68 65 72 65 20 53 20 69 73 20       where S is 
bb10: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  a NULL pointer s
bb20: 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65  hall disable the
bb30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 61  .**          [pa
bb40: 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  gecache memory a
bb50: 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a  llocator]..**.**
bb60: 20 7b 48 31 34 31 36 32 7d 20 41 20 73 75 63 63   {H14162} A succ
bb70: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
bb80: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
bb90: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
bba0: 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20  EAP],H,Z,N).**  
bbb0: 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a 20          where Z 
bbc0: 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65  and N are non-ne
bbd0: 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 20  gative integers 
bbe0: 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  and .**         
bbf0: 20 48 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20   H is a pointer 
bc00: 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d 65  to an aligned me
bc10: 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 20  mory buffer not 
bc20: 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20  less than.**    
bc30: 20 20 20 20 20 20 5a 20 62 79 74 65 73 20 69 6e        Z bytes in
bc40: 20 73 69 7a 65 20 73 68 61 6c 6c 20 65 6e 61 62   size shall enab
bc50: 6c 65 20 74 68 65 20 5b 6d 65 6d 73 79 73 35 5d  le the [memsys5]
bc60: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
bc70: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  r.**          an
bc80: 64 20 63 61 75 73 65 20 69 74 20 74 6f 20 75 73  d cause it to us
bc90: 65 20 62 75 66 66 65 72 20 53 20 61 73 20 69 74  e buffer S as it
bca0: 73 20 6d 65 6d 6f 72 79 20 73 6f 75 72 63 65 20  s memory source 
bcb0: 61 6e 64 20 74 6f 20 75 73 65 0a 2a 2a 20 20 20  and to use.**   
bcc0: 20 20 20 20 20 20 20 61 20 6d 69 6e 69 6d 75 6d         a minimum
bcd0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
bce0: 20 6f 66 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   of N..**.** {H1
bcf0: 34 31 36 35 7d 20 41 20 73 75 63 63 65 73 73 66  4165} A successf
bd00: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
bd10: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
bd20: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
bd30: 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20  ,H,Z,N).**      
bd40: 20 20 20 20 77 68 65 72 65 20 48 20 69 73 20 61      where H is a
bd50: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73 68   NULL pointer sh
bd60: 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65 0a  all disable the.
bd70: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 6d 65 6d  **          [mem
bd80: 73 79 73 35 5d 20 6d 65 6d 6f 72 79 20 61 6c 6c  sys5] memory all
bd90: 6f 63 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ocator..**.** {H
bda0: 31 34 31 36 38 7d 20 41 20 73 75 63 63 65 73 73  14168} A success
bdb0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
bdc0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
bdd0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
bde0: 41 53 49 44 45 5d 2c 5a 2c 4e 29 0a 2a 2a 20 20  ASIDE],Z,N).**  
bdf0: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 63 61          shall ca
be00: 75 73 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  use the default 
be10: 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
be20: 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
be30: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 20 20  figuration.**   
be40: 20 20 20 20 20 20 20 66 6f 72 20 6e 65 77 20 5b         for new [
be50: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
be60: 69 6f 6e 73 5d 20 74 6f 20 62 65 20 4e 20 73 6c  ions] to be N sl
be70: 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73 20 65  ots of Z bytes e
be80: 61 63 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ach..*/.SQLITE_E
be90: 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
bea0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
beb0: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
bec0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
bed0: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
bee0: 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 32  nnections  {H142
bef0: 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20  00} <S20000>.** 
bf00: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
bf10: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
bf20: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
bf30: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
bf40: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
bf50: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
bf60: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
bf70: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
bf80: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
bf90: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
bfa0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
bfb0: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
bfc0: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
bfd0: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
bfe0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
bff0: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
c000: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
c010: 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  ).  The.** sqlit
c020: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
c030: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c  nterface can onl
c040: 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69  y be used immedi
c050: 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74  ately after.** t
c060: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
c070: 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  ection is create
c080: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c090: 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _open()],.** [sq
c0a0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
c0b0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
c0c0: 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a  n_v2()].  .**.**
c0d0: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
c0e0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c0f0: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
c100: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  .)  is the.** co
c110: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
c120: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
c130: 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  de that indicate
c140: 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74  s what.** aspect
c150: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
c160: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
c170: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
c180: 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63  d..** The only c
c190: 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76  hoice for this v
c1a0: 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  alue is [SQLITE_
c1b0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
c1c0: 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62  DE]..** New verb
c1d0: 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
c1e0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
c1f0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
c200: 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69  QLite..** Additi
c210: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64  onal arguments d
c220: 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72  epend on the ver
c230: 62 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  b..**.** INVARIA
c240: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32  NTS:.**.** {H142
c250: 30 33 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  03} A call to [s
c260: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c270: 28 44 2c 56 2c 2e 2e 2e 29 5d 20 73 68 61 6c 6c  (D,V,...)] shall
c280: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
c290: 4f 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  OK].**          
c2a0: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
c2b0: 68 65 20 63 61 6c 6c 20 69 73 20 73 75 63 63 65  he call is succe
c2c0: 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ssful..**.** {H1
c2d0: 34 32 30 36 7d 20 49 66 20 6f 6e 65 20 6f 72 20  4206} If one or 
c2e0: 6d 6f 72 65 20 73 6c 6f 74 73 20 6f 66 20 74 68  more slots of th
c2f0: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  e [lookaside mem
c300: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66  ory allocator] f
c310: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
c320: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c330: 69 6f 6e 5d 20 44 20 61 72 65 20 69 6e 20 75 73  ion] D are in us
c340: 65 2c 20 74 68 65 6e 20 61 20 63 61 6c 6c 20 74  e, then a call t
c350: 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
c360: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c370: 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ](D,[SQLITE_DBCO
c380: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
c390: 2e 2e 2e 29 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  ...) shall.**   
c3a0: 20 20 20 20 20 20 20 66 61 69 6c 20 77 69 74 68         fail with
c3b0: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59   an [SQLITE_BUSY
c3c0: 5d 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0a 2a  ] return code..*
c3d0: 2a 0a 2a 2a 20 7b 48 31 34 32 30 39 7d 20 41 20  *.** {H14209} A 
c3e0: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
c3f0: 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  to .**          
c400: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
c410: 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42  ig](D,[SQLITE_DB
c420: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
c430: 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a  ],B,Z,N) where.*
c440: 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73 20  *          D is 
c450: 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  an open [databas
c460: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
c470: 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 70 6f  d Z and N are po
c480: 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  sitive.**       
c490: 20 20 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20     integers and 
c4a0: 42 20 69 73 20 61 6e 20 61 6c 69 67 6e 65 64 20  B is an aligned 
c4b0: 62 75 66 66 65 72 20 61 74 20 6c 65 61 73 74 20  buffer at least 
c4c0: 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  Z*N bytes in siz
c4d0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  e.**          sh
c4e0: 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 5b 6c  all cause the [l
c4f0: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
c500: 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44  allocator] for D
c510: 20 74 6f 20 75 73 65 20 62 75 66 66 65 72 20 42   to use buffer B
c520: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69   .**          wi
c530: 74 68 20 4e 20 73 6c 6f 74 73 20 6f 66 20 5a 20  th N slots of Z 
c540: 62 79 74 65 73 20 65 61 63 68 2e 0a 2a 2a 0a 2a  bytes each..**.*
c550: 2a 20 7b 48 31 34 32 31 32 7d 20 41 20 73 75 63  * {H14212} A suc
c560: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
c570: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
c580: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 5d  lite3_db_config]
c590: 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  (D,[SQLITE_DBCON
c5a0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42  FIG_LOOKASIDE],B
c5b0: 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a 2a 20 20  ,Z,N) where.**  
c5c0: 20 20 20 20 20 20 20 20 44 20 69 73 20 61 6e 20          D is an 
c5d0: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
c5e0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5a  onnection] and Z
c5f0: 20 61 6e 64 20 4e 20 61 72 65 20 70 6f 73 69 74   and N are posit
c600: 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
c610: 69 6e 74 65 67 65 72 73 20 61 6e 64 20 42 20 69  integers and B i
c620: 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  s NULL pointer s
c630: 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 0a 2a  hall cause the.*
c640: 2a 20 20 20 20 20 20 20 20 20 20 5b 6c 6f 6f 6b  *          [look
c650: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
c660: 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44 20 74 6f  ocator] for D to
c670: 20 61 20 6f 62 74 61 69 6e 20 5a 2a 4e 20 62 79   a obtain Z*N by
c680: 74 65 20 62 75 66 66 65 72 0a 2a 2a 20 20 20 20  te buffer.**    
c690: 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 70        from the p
c6a0: 72 69 6d 61 72 79 20 6d 65 6d 6f 72 79 20 61 6c  rimary memory al
c6b0: 6c 6f 63 61 74 6f 72 20 61 6e 64 20 75 73 65 20  locator and use 
c6c0: 74 68 61 74 20 62 75 66 66 65 72 0a 2a 2a 20 20  that buffer.**  
c6d0: 20 20 20 20 20 20 20 20 77 69 74 68 20 4e 20 6c          with N l
c6e0: 6f 6f 6b 61 73 69 64 65 20 73 6c 6f 74 73 20 6f  ookaside slots o
c6f0: 66 20 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a  f Z bytes each..
c700: 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31 35 7d 20 41  **.** {H14215} A
c710: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
c720: 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   to .**         
c730: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
c740: 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44  fig](D,[SQLITE_D
c750: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
c760: 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a  E],B,Z,N) where.
c770: 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73  **          D is
c780: 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61   an open [databa
c790: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
c7a0: 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 7a  nd Z and N are z
c7b0: 65 72 6f 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20  ero shall.**    
c7c0: 20 20 20 20 20 20 64 69 73 61 62 6c 65 20 74 68        disable th
c7d0: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  e [lookaside mem
c7e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66  ory allocator] f
c7f0: 6f 72 20 44 2e 0a 2a 2a 0a 2a 2a 0a 2a 2f 0a 53  or D..**.**.*/.S
c800: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
c810: 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  AL int sqlite3_d
c820: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
c830: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
c840: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c850: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
c860: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31  ion Routines {H1
c870: 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a  0155} <S20120>.*
c880: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
c890: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
c8a0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
c8b0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
c8c0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
c8d0: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
c8e0: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
c8f0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
c900: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
c910: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
c920: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
c930: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
c940: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
c950: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
c960: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
c970: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
c980: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
c990: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
c9a0: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
c9b0: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
c9c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
c9d0: 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74  LLOC].  By creat
c9e0: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
c9f0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
ca00: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
ca10: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
ca20: 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f  fig()] during co
ca30: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a  nfiguration, an.
ca40: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  ** application c
ca50: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
ca60: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
ca70: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
ca80: 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c  ystem.** for SQL
ca90: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
caa0: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
cab0: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
cac0: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
cad0: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
cae0: 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  h a built-in mem
caf0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
cb00: 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74  at is.** perfect
cb10: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
cb20: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
cb30: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
cb40: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
cb50: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
cb60: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
cb70: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
cb80: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
cb90: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
cba0: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
cbb0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
cbc0: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
cbd0: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
cbe0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
cbf0: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
cc00: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
cc10: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
cc20: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
cc30: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
cc40: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
cc50: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
cc60: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
cc70: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
cc80: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
cc90: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
cca0: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
ccb0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
ccc0: 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64  lloc, xFree, and
ccd0: 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64   xRealloc method
cce0: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
ccf0: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
cd00: 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65  , free(), and re
cd10: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e  alloc() function
cd20: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
cd30: 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ard library..**.
cd40: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
cd50: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
cd60: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
cd70: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
cd80: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
cd90: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
cda0: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
cdb0: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
cdc0: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
cdd0: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
cde0: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
cdf0: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
ce00: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
ce10: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
ce20: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
ce30: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
ce40: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
ce50: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
ce60: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
ce70: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
ce80: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
ce90: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
cea0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
ceb0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
cec0: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
ced0: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
cee0: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
cef0: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
cf00: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
cf10: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
cf20: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a   power of 2..**.
cf30: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
cf40: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
cf50: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
cf60: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
cf70: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
cf80: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
cf90: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
cfa0: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
cfb0: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
cfc0: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
cfd0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
cfe0: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
cff0: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
d000: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
d010: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
d020: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
d030: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
d040: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
d050: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
d060: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
d070: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
d080: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
d090: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79  xShutdown..*/.ty
d0a0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
d0b0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d0c0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
d0d0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
d0e0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d0f0: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
d100: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
d110: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
d120: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
d130: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
d140: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
d150: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
d160: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
d170: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
d180: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
d190: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
d1a0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
d1b0: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
d1c0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
d1d0: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
d1e0: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
d1f0: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
d200: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
d210: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
d220: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
d230: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
d240: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
d250: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
d260: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
d270: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
d280: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
d290: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
d2a0: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
d2b0: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
d2c0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
d2d0: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
d2e0: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
d2f0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
d300: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
d310: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
d320: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
d330: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
d340: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31  tion Options {H1
d350: 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0160} <S20000>.*
d360: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
d370: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
d380: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
d390: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
d3a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d3b0: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
d3c0: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
d3d0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
d3e0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
d3f0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
d400: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
d410: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d420: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
d430: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
d440: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
d450: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
d460: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d470: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
d480: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
d490: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
d4a0: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
d4b0: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
d4c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d4d0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
d4e0: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
d4f0: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
d500: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
d510: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
d520: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
d530: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
d540: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
d550: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
d560: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d570: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
d580: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
d590: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d5a0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
d5b0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
d5c0: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
d5d0: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
d5e0: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e  on.  This option
d5f0: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
d600: 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
d610: 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
d620: 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
d630: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
d640: 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
d650: 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  hread.</dd>.**.*
d660: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d670: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
d680: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
d690: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
d6a0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
d6b0: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
d6c0: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
d6d0: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
d6e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
d6f0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
d700: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
d710: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
d720: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
d730: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
d740: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
d750: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d760: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
d770: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
d780: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
d790: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
d7a0: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
d7b0: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
d7c0: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
d7d0: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
d7e0: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
d7f0: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
d800: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
d810: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
d820: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d830: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
d840: 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65 20 5b  time.  See the [
d850: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 0a  threading mode].
d860: 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  ** documentation
d870: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
d880: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64  information.</dd
d890: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d8a0: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
d8b0: 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
d8c0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
d8d0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
d8e0: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
d8f0: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
d900: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
d910: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
d920: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
d930: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
d940: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
d950: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
d960: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
d970: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
d980: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
d990: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
d9a0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d9b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
d9c0: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
d9d0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
d9e0: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
d9f0: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
da00: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
da10: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
da20: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
da30: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
da40: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
da50: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
da60: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
da70: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
da80: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
da90: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
daa0: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
dab0: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
dac0: 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  ..** See the [th
dad0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
dae0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
daf0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
db00: 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  mation.</dd>.**.
db10: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
db20: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
db30: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
db40: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
db50: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
db60: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
db70: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
db80: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
db90: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
dba0: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
dbb0: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
dbc0: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
dbd0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
dbe0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
dbf0: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
dc00: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
dc10: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
dc20: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
dc30: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
dc40: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
dc50: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
dc60: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
dc70: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
dc80: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
dc90: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
dca0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
dcb0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
dcc0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
dcd0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
dce0: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
dcf0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
dd00: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
dd10: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
dd20: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
dd30: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
dd40: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
dd50: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
dd60: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
dd70: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
dd80: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
dd90: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
dda0: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
ddb0: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
ddc0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ddd0: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
dde0: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
ddf0: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
de00: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
de10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
de20: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
de30: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
de40: 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
de50: 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
de60: 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
de70: 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
de80: 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
de90: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
dea0: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
deb0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
dec0: 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 57  ** statistics. W
ded0: 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68  hen disabled, th
dee0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
def0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
df00: 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65  come .** non-ope
df10: 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
df20: 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
df30: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
df40: 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
df50: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
df60: 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
df70: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
df80: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
df90: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
dfa0: 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
dfb0: 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f  **   </ul>.** </
dfc0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
dfd0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
dfe0: 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
dff0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
e000: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
e010: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
e020: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
e030: 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
e040: 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
e050: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
e060: 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74  ts:  A pointer t
e070: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68  o the memory, th
e080: 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
e090: 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  h scratch buffer
e0a0: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
e0b0: 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72 73  umber of buffers
e0c0: 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a   (N).  The sz.**
e0d0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
e0e0: 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  e a multiple of 
e0f0: 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61 6d  16. The sz param
e100: 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61  eter should be a
e110: 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c 61   few bytes.** la
e120: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61 63  rger than the ac
e130: 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70 61  tual scratch spa
e140: 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65 20  ce required due 
e150: 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61  internal overhea
e160: 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 0a  d..** The first.
e170: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
e180: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
e190: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
e1a0: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
e1b0: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   of memory..** S
e1c0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
e1d0: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  o more than one 
e1e0: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 61  scratch buffer a
e1f0: 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61  t once per threa
e200: 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  d, so.** N shoul
e210: 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20  d be set to the 
e220: 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
e230: 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
e240: 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70  ds.  The sz.** p
e250: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
e260: 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20 73  be 6 times the s
e270: 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
e280: 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
e290: 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63   size..** Scratc
e2a0: 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75 73  h buffers are us
e2b0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
e2c0: 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20  e btree balance 
e2d0: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a  operation.  If.*
e2e0: 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c 61  * The btree bala
e2f0: 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69 74  ncer needs addit
e300: 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79  ional memory bey
e310: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
e320: 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74  ided by.** scrat
e330: 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69 66  ch buffers or if
e340: 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66 66   no scratch buff
e350: 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65 63  er space is spec
e360: 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69  ified, then SQLi
e370: 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73  te.** goes to [s
e380: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
e390: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
e3a0: 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c  emory it needs.<
e3b0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e3c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
e3d0: 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
e3e0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
e3f0: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
e400: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
e410: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
e420: 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64  use for.** the d
e430: 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
e440: 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
e450: 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ult page cache i
e460: 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a  mplemenation.  .
e470: 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
e480: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
e490: 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
e4a0: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
e4b0: 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
e4c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
e4d0: 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
e4e0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
e4f0: 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a  _PCACHE option..
e500: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
e510: 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
e520: 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70  this option: A p
e530: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
e540: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
e550: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
e560: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
e570: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
e580: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
e590: 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  sz argument must
e5a0: 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74   be a power of t
e5b0: 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
e5c0: 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 20 66  nd 32768.  The f
e5d0: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
e5e0: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
e5f0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
e600: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
e610: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
e620: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
e630: 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
e640: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
e650: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
e660: 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
e670: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
e680: 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
e690: 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
e6a0: 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 64  to cache.  If ad
e6b0: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
e6c0: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
e6d0: 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
e6e0: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
e6f0: 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
e700: 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
e710: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
e720: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
e730: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
e740: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
e750: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
e760: 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20  n might use one 
e770: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e  or more of the N
e780: 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64   buffers to hold
e790: 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f   .** memory acco
e7a0: 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69  unting informati
e7b0: 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  on. </dd>.**.** 
e7c0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
e7d0: 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
e7e0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
e7f0: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
e800: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
e810: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
e820: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
e830: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
e840: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e850: 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
e860: 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
e870: 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
e880: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
e890: 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
e8a0: 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
e8b0: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
e8c0: 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f   arguments: A po
e8d0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
e8e0: 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ory, the number 
e8f0: 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
e900: 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
e910: 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
e920: 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
e930: 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66 69  e.  If.** the fi
e940: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
e950: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
e960: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
e970: 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
e980: 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
e990: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
e9a0: 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
e9b0: 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
e9c0: 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
e9d0: 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
e9e0: 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
e9f0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
ea00: 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a  ALLOC].  If the.
ea10: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
ea20: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
ea30: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
ea40: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
ea50: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
ea60: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
ea70: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
ea80: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
ea90: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
eaa0: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
eab0: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
eac0: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
ead0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
eae0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
eaf0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
eb00: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
eb10: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
eb20: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
eb30: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
eb40: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
eb50: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
eb60: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
eb70: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
eb80: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
eb90: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
eba0: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
ebb0: 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
ebc0: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
ebd0: 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
ebe0: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
ebf0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
ec00: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
ec10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
ec20: 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
ec30: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
ec40: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
ec50: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
ec60: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
ec70: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
ec80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
ec90: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
eca0: 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
ecb0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
ecc0: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
ecd0: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
ece0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
ecf0: 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
ed00: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20  utines..** This 
ed10: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
ed20: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
ed30: 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
ed40: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
ed50: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
ed60: 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
ed70: 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
ed80: 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
ed90: 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
eda0: 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
edb0: 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ample.</dd>.**.*
edc0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
edd0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
ede0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
edf0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
ee00: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
ee10: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66  etermine the def
ee20: 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  ault.** memory a
ee30: 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69  llcation lookasi
ee40: 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e  de optimization.
ee50: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
ee60: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
ee70: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
ee80: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
ee90: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
eea0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
eeb0: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
eec0: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
eed0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
eee0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
eef0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
ef00: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
ef10: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
ef20: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
ef30: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
ef40: 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61   pointer to.** a
ef50: 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
ef60: 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
ef70: 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
ef80: 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
ef90: 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
efa0: 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
efb0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
efc0: 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  .  SQLite makes 
efd0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
efe0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73   object and uses
eff0: 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63   it for page cac
f000: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
f010: 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  tions.</dd>.**.*
f020: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
f030: 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64  FIG_GETPCACHE</d
f040: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
f050: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
f060: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
f070: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
f080: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
f090: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
f0a0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  s] object.  SQLi
f0b0: 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65  te copies of the
f0c0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65   current.** page
f0d0: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
f0e0: 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
f0f0: 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
f100: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
f110: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
f120: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
f130: 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
f140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
f150: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
f160: 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
f170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f180: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
f190: 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
f1a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f1b0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
f1c0: 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
f1d0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
f1e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f1f0: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
f200: 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
f210: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
f220: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f230: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
f240: 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
f250: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
f260: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
f270: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
f280: 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
f290: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
f2a0: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
f2b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
f2c0: 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
f2d0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
f2e0: 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
f2f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f300: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
f310: 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
f320: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f330: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
f340: 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
f350: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
f360: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
f370: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
f380: 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
f390: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
f3a0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
f3b0: 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
f3c0: 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
f3d0: 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
f3e0: 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
f3f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f400: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
f410: 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
f420: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f430: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
f440: 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c        14  /* sql
f450: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
f460: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
f470: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
f480: 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f  TPCACHE    15  /
f490: 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
f4a0: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a  _methods* */../*
f4b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
f4c0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
f4d0: 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c 53 32  ons {H10170} <S2
f4e0: 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0000>.** EXPERIM
f4f0: 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ENTAL.**.** Thes
f500: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
f510: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
f520: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
f530: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
f540: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
f550: 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
f560: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
f570: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
f580: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
f590: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
f5a0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
f5b0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
f5c0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
f5d0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
f5e0: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
f5f0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
f600: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
f610: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
f620: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
f630: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
f640: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
f650: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
f660: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
f670: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
f680: 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
f690: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
f6a0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
f6b0: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
f6c0: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
f6d0: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
f6e0: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
f6f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f700: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
f710: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
f720: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
f730: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
f740: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
f750: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
f760: 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
f770: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
f780: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
f790: 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
f7a0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
f7b0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
f7c0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
f7d0: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
f7e0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f7f0: 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
f800: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
f810: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
f820: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
f830: 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
f840: 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
f850: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 20  kaside memory.  
f860: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
f870: 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c  ument may be NUL
f880: 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
f890: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
f8a0: 63 61 74 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  cate the lookasi
f8b0: 64 65 0a 2a 2a 20 62 75 66 66 65 72 20 69 74 73  de.** buffer its
f8c0: 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
f8d0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54  e3_malloc()].  T
f8e0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
f8f0: 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
f900: 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
f910: 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
f920: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 61 72  and the third ar
f930: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
f940: 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
f950: 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
f960: 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
f970: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
f980: 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
f990: 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
f9a0: 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
f9b0: 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
f9c0: 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
f9d0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  s.</dd>.**.** </
f9e0: 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
f9f0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
fa00: 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31  OOKASIDE    1001
fa10: 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
fa20: 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt */.../*.** CA
fa30: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
fa40: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
fa50: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
fa60: 7b 48 31 32 32 30 30 7d 20 3c 53 31 30 37 30 30  {H12200} <S10700
fa70: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
fa80: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
fa90: 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
faa0: 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
fab0: 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
fac0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
fad0: 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
fae0: 66 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78  f SQLite. The ex
faf0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
fb00: 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
fb10: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
fb20: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
fb30: 6d 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73  mpatibility cons
fb40: 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  iderations..**.*
fb50: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
fb60: 0a 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45 61 63  .** {H12201} Eac
fb70: 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20  h new [database 
fb80: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c  connection] shal
fb90: 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20 20  l have the.**   
fba0: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
fbb0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
fbc0: 65 61 74 75 72 65 20 64 69 73 61 62 6c 65 64 20  eature disabled 
fbd0: 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
fbe0: 2a 20 7b 48 31 32 32 30 32 7d 20 54 68 65 20 5b  * {H12202} The [
fbf0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
fc00: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c  _result_codes(D,
fc10: 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  F)] interface sh
fc20: 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20  all enable.**   
fc30: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
fc40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
fc50: 6f 72 20 74 68 65 20 20 5b 64 61 74 61 62 61 73  or the  [databas
fc60: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
fc70: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74  **          if t
fc80: 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 20 69  he F parameter i
fc90: 73 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62  s true, or disab
fca0: 6c 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20  le them if F is 
fcb0: 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  false..*/.int sq
fcc0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
fcd0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
fce0: 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
fcf0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fd00: 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
fd10: 6f 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c 53  owid {H12220} <S
fd20: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63  10700>.**.** Eac
fd30: 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
fd40: 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
fd50: 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
fd60: 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
fd70: 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
fd80: 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
fd90: 5d 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20  ]. The rowid is 
fda0: 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
fdb0: 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
fdc0: 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
fdd0: 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
fde0: 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
fdf0: 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
fe00: 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
fe10: 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
fe20: 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
fe30: 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74  mns. If.** the t
fe40: 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
fe50: 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
fe60: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
fe70: 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
fe80: 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
fe90: 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
fea0: 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  id..**.** This r
feb0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
fec0: 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
fed0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
fee0: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
fef0: 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61  ERT] into the da
ff00: 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20  tabase from the 
ff10: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ff20: 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
ff30: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20  first argument. 
ff40: 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75   If no successfu
ff50: 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
ff60: 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
ff70: 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
ff80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
ff90: 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
ffa0: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 5b 49 4e  .**.** If an [IN
ffb0: 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
ffc0: 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74  hin a trigger, t
ffd0: 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  hen the [rowid] 
ffe0: 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
fff0: 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e  ** row is return
10000 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
10010 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ne as long as th
10020 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e  e trigger is run
10030 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
10040 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65  e the trigger te
10050 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61  rminates, the va
10060 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
10070 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
10080 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c  reverts to the l
10090 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74  ast value insert
100a0 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  ed before the tr
100b0 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a  igger fired..**.
100c0 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  ** An [INSERT] t
100d0 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
100e0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
100f0 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
10100 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
10110 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
10120 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
10130 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
10140 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
10150 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20  e.  Thus INSERT 
10160 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
10170 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
10180 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
10190 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
101a0 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
101b0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
101c0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
101d0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
101e0 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
101f0 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49  n fails.  When I
10200 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
10210 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
10220 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
10230 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
10240 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
10250 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
10260 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
10270 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
10280 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
10290 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
102a0 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
102b0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
102c0 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
102d0 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
102e0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
102f0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46  terface..**.** F
10300 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
10310 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
10320 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
10330 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
10340 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
10350 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
10360 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
10370 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   back..**.** INV
10380 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
10390 48 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c  H12221} The [sql
103a0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
103b0 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69  _rowid()] functi
103c0 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a  on shall return.
103d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
103e0 5b 72 6f 77 69 64 5d 0a 2a 2a 20 20 20 20 20 20  [rowid].**      
103f0 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73 74 20      of the most 
10400 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
10410 6c 20 5b 49 4e 53 45 52 54 5d 20 70 65 72 66 6f  l [INSERT] perfo
10420 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61 6d 65  rmed on the same
10430 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
10440 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10450 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68  n] and within th
10460 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72  e same or higher
10470 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20   level.**       
10480 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65     trigger conte
10490 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74  xt, or zero if t
104a0 68 65 72 65 20 68 61 76 65 20 62 65 65 6e 20 6e  here have been n
104b0 6f 20 71 75 61 6c 69 66 79 69 6e 67 0a 2a 2a 20  o qualifying.** 
104c0 20 20 20 20 20 20 20 20 20 5b 49 4e 53 45 52 54           [INSERT
104d0 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
104e0 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20 54 68 65  .** {H12223} The
104f0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
10500 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66  nsert_rowid()] f
10510 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65  unction shall re
10520 74 75 72 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  turn the.**     
10530 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20       same value 
10540 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
10550 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
10560 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20  r context.**    
10570 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c        immediatel
10580 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74  y before and aft
10590 65 72 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  er a [ROLLBACK].
105a0 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
105b0 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 33  NS:.**.** {A1223
105c0 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65  2} If a separate
105d0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
105e0 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
105f0 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  on the same.**  
10600 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
10610 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
10620 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
10630 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
10640 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
10650 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
10660 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
10670 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
10680 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
10690 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
106a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
106b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
106c0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
106d0 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
106e0 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20    unpredictable 
106f0 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
10700 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
10710 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
10720 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20 69            last i
10730 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
10740 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
10750 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
10760 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
10770 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
10780 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
10790 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
107a0 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d  odified {H12240}
107b0 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10600>.**.** 
107c0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
107d0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
107e0 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
107f0 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
10800 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
10810 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
10820 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
10830 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
10840 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
10850 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
10860 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
10870 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
10880 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
10890 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
108a0 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
108b0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
108c0 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
108d0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
108e0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
108f0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
10900 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
10910 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
10920 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  rs are not count
10930 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
10940 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
10950 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  es()] function.*
10960 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  * to find the to
10970 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
10980 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  anges including 
10990 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
109a0 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a  y triggers..**.*
109b0 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  * A "row change"
109c0 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
109d0 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
109e0 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
109f0 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
10a00 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
10a10 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
10a20 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
10a30 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
10a40 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
10a50 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
10a60 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
10a70 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
10a80 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44  RT processing, D
10a90 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79  ROP TABLE, or by
10aa0 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   any other.** me
10ab0 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20  chanisms do not 
10ac0 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20  count as direct 
10ad0 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
10ae0 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f  ** A "trigger co
10af0 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70  ntext" is a scop
10b00 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74  e of execution t
10b10 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a  hat begins and.*
10b20 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20  * ends with the 
10b30 73 63 72 69 70 74 20 6f 66 20 61 20 74 72 69 67  script of a trig
10b40 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73  ger.  Most SQL s
10b50 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
10b60 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
10b70 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
10b80 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
10b90 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
10ba0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
10bb0 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
10bc0 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
10bd0 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
10be0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
10bf0 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
10c00 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
10c10 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
10c20 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
10c30 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
10c40 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
10c50 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43  uration..**.** C
10c60 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
10c70 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
10c80 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
10c90 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
10ca0 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
10cb0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
10cc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
10cd0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
10ce0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
10cf0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
10d00 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
10d10 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
10d20 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
10d30 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
10d40 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
10d50 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
10d60 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61  ** Thus, when ca
10d70 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
10d80 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
10d90 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
10da0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
10db0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
10dc0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
10dd0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
10de0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
10df0 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
10e00 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69  e top level.  Wi
10e10 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
10e20 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
10e30 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
10e40 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
10e50 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
10e60 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
10e70 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
10e80 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
10e90 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
10ea0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
10eb0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
10ec0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
10ed0 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
10ee0 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
10ef0 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
10f00 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
10f10 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
10f20 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
10f30 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
10f40 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
10f50 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a  r own context..*
10f60 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
10f70 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61  ements the comma
10f80 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  nd "DELETE FROM 
10f90 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61  table" without a
10fa0 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a   WHERE clause.**
10fb0 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64   by dropping and
10fc0 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20   recreating the 
10fd0 74 61 62 6c 65 2e 20 20 44 6f 69 6e 67 20 73 6f  table.  Doing so
10fe0 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20   is much faster 
10ff0 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68  than going.** th
11000 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69  rough and deleti
11010 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c  ng individual el
11020 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20  ements from the 
11030 74 61 62 6c 65 2e 20 20 42 65 63 61 75 73 65 20  table.  Because 
11040 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d  of this.** optim
11050 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c  ization, the del
11060 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54  etions in "DELET
11070 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72  E FROM table" ar
11080 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65  e not row change
11090 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f  s and.** will no
110a0 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20  t be counted by 
110b0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
110c0 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65  ges() or [sqlite
110d0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
110e0 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c  )].** functions,
110f0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
11100 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
11110 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
11120 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e  originally.** in
11130 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20   the table.  To 
11140 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
11150 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
11160 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
11170 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
11180 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
11190 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
111a0 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75    Or recompile u
111b0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
111c0 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54  ITE_OMIT_TRUNCAT
111d0 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20  E_OPTIMIZATION] 
111e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
111f0 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ion to disable t
11200 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  he.** optimizati
11210 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65  on on all querie
11220 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
11230 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  NTS:.**.** {H122
11240 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
11250 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
11260 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72  tion shall retur
11270 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  n the number of.
11280 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 20  **          row 
11290 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
112a0 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
112b0 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
112c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
112d0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
112e0 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  t on the same da
112f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11300 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  n and.**        
11310 20 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d    within the sam
11320 65 20 6f 72 20 68 69 67 68 65 72 20 74 72 69 67  e or higher trig
11330 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20  ger context, or 
11340 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61  zero if there ha
11350 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ve.**          n
11360 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c  ot been any qual
11370 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67  ifying row chang
11380 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34  es..**.** {H1224
11390 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66  3} Statements of
113a0 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54   the form "DELET
113b0 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65  E FROM tablename
113c0 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20  " with no.**    
113d0 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 75        WHERE clau
113e0 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73  se shall cause s
113f0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
11400 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
11410 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
11420 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72  )] to return zer
11430 6f 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  o, regardless of
11440 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
11450 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
11460 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68  originally in th
11470 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41  e table..**.** A
11480 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
11490 2a 20 7b 41 31 32 32 35 32 7d 20 49 66 20 61 20  * {A12252} If a 
114a0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
114b0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
114c0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
114d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
114e0 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 20            while 
114f0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
11500 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
11510 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
11520 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  turned.**       
11530 20 20 20 69 73 20 75 6e 70 72 65 64 69 63 74 61     is unpredicta
11540 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
11550 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
11560 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
11570 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
11580 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
11590 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
115a0 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 36 30  Modified {H12260
115b0 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10600>.**.**
115c0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
115d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
115e0 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
115f0 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52   caused by INSER
11600 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20  T,.** UPDATE or 
11610 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
11620 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
11630 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11640 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
11650 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75   The count inclu
11660 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20  des all changes 
11670 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72  from all trigger
11680 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65   contexts.  Howe
11690 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
116a0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
116b0 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
116c0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50  to implement REP
116d0 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73  LACE constraints
116e0 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
116f0 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
11700 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74  ssing, or DROP t
11710 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e  able processing.
11720 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20  .** The changes 
11730 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73  are counted as s
11740 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65  oon as the state
11750 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
11760 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c  them is.** compl
11770 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
11780 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
11790 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
117a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
117b0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
117c0 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
117d0 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
117e0 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
117f0 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
11800 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48  le" without a WH
11810 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79  ERE clause.** by
11820 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
11830 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
11840 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75  le.  (This is mu
11850 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67  ch faster than g
11860 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20  oing.** through 
11870 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64  and deleting ind
11880 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73  ividual elements
11890 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e   from the table.
118a0 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  )  Because of th
118b0 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  is.** optimizati
118c0 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e  on, the deletion
118d0 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f  s in "DELETE FRO
118e0 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74  M table" are not
118f0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64   row changes and
11900 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  .** will not be 
11910 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73  counted by the s
11920 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
11930 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   or [sqlite3_tot
11940 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a  al_changes()].**
11950 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61   functions, rega
11960 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
11970 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
11980 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
11990 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20  nally.** in the 
119a0 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61  table.  To get a
119b0 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
119c0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
119d0 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20  f rows deleted, 
119e0 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46  use.** "DELETE F
119f0 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
11a00 31 22 20 69 6e 73 74 65 61 64 2e 20 20 20 4f 72  1" instead.   Or
11a10 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67   recompile using
11a20 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
11a30 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50  OMIT_TRUNCATE_OP
11a40 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70  TIMIZATION] comp
11a50 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11a60 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a  to disable the.*
11a70 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f  * optimization o
11a80 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a  n all queries..*
11a90 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
11aa0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
11ab0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
11ac0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
11ad0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 31  S:.**.** {H12261
11ae0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  } The [sqlite3_t
11af0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
11b00 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61  returns the tota
11b10 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20  l number.**     
11b20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68 61 6e       of row chan
11b30 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e  ges caused by IN
11b40 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e  SERT, UPDATE, an
11b50 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20  d/or DELETE.**  
11b60 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
11b70 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ts on the same [
11b80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11b90 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20  ion], in any.** 
11ba0 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72           trigger
11bb0 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20   context, since 
11bc0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
11bd0 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72 65 61  nection was crea
11be0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ted..**.** {H122
11bf0 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f  63} Statements o
11c00 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45  f the form "DELE
11c10 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d  TE FROM tablenam
11c20 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20  e" with no.**   
11c30 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61         WHERE cla
11c40 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68  use shall not ch
11c50 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
11c60 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20  eturned.**      
11c70 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
11c80 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
11c90 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
11ca0 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32  ONS:.**.** {A122
11cb0 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  64} If a separat
11cc0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
11cd0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
11ce0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
11cf0 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
11d00 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
11d10 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
11d20 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
11d30 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
11d40 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65           returne
11d50 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
11d60 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
11d70 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
11d80 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
11d90 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
11da0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11db0 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
11dc0 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b  -Running Query {
11dd0 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e  H12270} <S30500>
11de0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
11df0 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
11e00 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
11e10 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
11e20 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
11e30 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
11e40 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
11e50 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
11e60 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
11e70 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
11e80 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
11e90 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
11ea0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
11eb0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
11ec0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
11ed0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
11ee0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
11ef0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
11f00 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63   It is safe to c
11f10 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
11f20 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
11f30 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
11f40 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
11f50 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
11f60 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
11f70 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
11f80 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
11f90 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
11fa0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
11fb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11fc0 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
11fd0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
11fe0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
11ff0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12000 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
12010 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72  * If an SQL oper
12020 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
12030 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
12040 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
12050 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
12060 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
12070 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
12080 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
12090 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
120a0 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
120b0 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
120c0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
120d0 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61  .** An SQL opera
120e0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
120f0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
12100 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
12110 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74  ERRUPT]..** If t
12120 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
12130 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
12140 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
12150 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
12160 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
12170 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
12180 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
12190 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
121a0 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
121b0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
121c0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
121d0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
121e0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68 61  3_interrupt() ha
121f0 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
12200 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
12210 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
12220 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
12230 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
12240 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  rns..**.** INVAR
12250 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
12260 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2271} The [sqlit
12270 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20  e3_interrupt()] 
12280 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66  interface will f
12290 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67  orce all running
122a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
122b0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
122c0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
122d0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
122e0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
122f0 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74       to halt aft
12300 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74  er processing at
12310 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69   most one additi
12320 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61 74 61  onal row of data
12330 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 32 7d  ..**.** {H12272}
12340 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
12350 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  nt that is inter
12360 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74  rupted by [sqlit
12370 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
12380 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
12390 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
123a0 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a  INTERRUPT]..**.*
123b0 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
123c0 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20 49 66  *.** {A12279} If
123d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
123e0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
123f0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
12400 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20  nterrupt()].**  
12410 20 20 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69          is runni
12420 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
12430 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
12440 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
12450 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12460 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
12470 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
12480 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
12490 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
124a0 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20  mplete {H10510} 
124b0 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70200>.**.** T
124c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
124d0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d  e useful for com
124e0 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
124f0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
12500 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
12510 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
12520 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70  ems to form comp
12530 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74 65  lete a SQL state
12540 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
12550 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
12560 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
12570 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
12580 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
12590 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68  for parsing.  Th
125a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
125b0 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
125c0 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
125d0 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
125e0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
125f0 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65  tement.  A state
12600 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
12610 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
12620 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
12630 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
12640 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
12650 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a  fragment of a.**
12660 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
12670 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69  statement.  Semi
12680 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
12690 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
126a0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
126b0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
126c0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
126d0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
126e0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
126f0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
12700 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
12710 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
12720 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
12730 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
12740 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
12750 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
12760 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
12770 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
12780 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
12790 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
127a0 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
127b0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
127c0 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
127d0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
127e0 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d 20 41  **.** {H10511} A
127f0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 61 6c   successful eval
12800 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  uation of [sqlit
12810 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f  e3_complete()] o
12820 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
12830 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
12840 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20 73  6()] functions s
12850 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
12860 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65 72 69   return a numeri
12870 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  c 1 if and only 
12880 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f 6e 2d  if the last non-
12890 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 20 20  whitespace.**   
128a0 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69 6e 20         token in 
128b0 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 20 61  their input is a
128c0 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 20   semicolon that 
128d0 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65  is not in betwee
128e0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
128f0 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20  e BEGIN and END 
12900 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 49 47  of a CREATE TRIG
12910 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  GER statement..*
12920 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20 49 66  *.** {H10512} If
12930 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
12940 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
12950 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e 76 6f  s during an invo
12960 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  cation.**       
12970 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63     of [sqlite3_c
12980 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20 5b 73  omplete()] or [s
12990 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
129a0 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  6()] then the.**
129b0 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e            routin
129c0 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b  e shall return [
129d0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
129e0 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
129f0 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 32 7d  :.**.** {A10512}
12a00 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
12a10 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
12a20 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
12a30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
12a40 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73           UTF-8 s
12a50 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  tring..**.** {A1
12a60 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20  0513} The input 
12a70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
12a80 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
12a90 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
12aa0 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
12ab0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
12ac0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
12ad0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
12ae0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
12af0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
12b00 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
12b10 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
12b20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
12b30 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
12b40 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
12b50 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
12b60 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30  Y Errors {H12310
12b70 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S40400>.**.**
12b80 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65   This routine se
12b90 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
12ba0 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
12bb0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  t be invoked whe
12bc0 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
12bd0 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
12be0 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
12bf0 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  able that anothe
12c00 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
12c10 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
12c20 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
12c30 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
12c40 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
12c50 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
12c60 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
12c70 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
12c80 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
12c90 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
12ca0 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68   the lock. If th
12cb0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
12cc0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
12cd0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
12ce0 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  k will be invoke
12cf0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
12d00 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
12d10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
12d20 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73  o the handler is
12d30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
12d40 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
12d50 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
12d60 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
12d70 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
12d80 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f  ler().  The seco
12d90 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
12da0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61  * the handler ca
12db0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
12dc0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
12dd0 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
12de0 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
12df0 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
12e00 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
12e10 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20   If the.** busy 
12e20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
12e30 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
12e40 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
12e50 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
12e60 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
12e70 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
12e80 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
12e90 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
12ea0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
12eb0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
12ec0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
12ed0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
12ee0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
12ef0 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
12f00 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
12f10 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
12f20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
12f30 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
12f40 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
12f50 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
12f60 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
12f70 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
12f80 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
12f90 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51  ontention. If SQ
12fa0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
12fb0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
12fc0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
12fd0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
12fe0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
12ff0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
13000 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
13010 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
13020 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13030 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
13040 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
13050 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
13060 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
13070 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
13080 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
13090 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
130a0 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
130b0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
130c0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
130d0 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
130e0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
130f0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
13100 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
13110 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
13120 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
13130 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
13140 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
13150 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
13160 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
13170 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
13180 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
13190 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
131a0 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
131b0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
131c0 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
131d0 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
131e0 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
131f0 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
13200 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
13210 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
13220 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
13230 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
13240 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
13250 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
13260 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
13270 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
13280 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
13290 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
132a0 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
132b0 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
132c0 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
132d0 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  oceed..**.** The
132e0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
132f0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
13300 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
13310 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
13320 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
13330 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13340 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
13350 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
13360 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
13370 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
13380 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
13390 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
133a0 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
133b0 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
133c0 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
133d0 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
133e0 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
133f0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
13400 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
13410 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
13420 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
13430 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
13440 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
13450 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
13460 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
13470 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
13480 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
13490 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61  s.  If it is una
134a0 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
134b0 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
134c0 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
134d0 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
134e0 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
134f0 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
13500 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
13510 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
13520 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
13530 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
13540 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
13550 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
13560 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
13570 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72  CKED].  This err
13580 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
13590 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
135a0 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
135b0 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
135c0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
135d0 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
135e0 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
135f0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
13600 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
13610 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
13620 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
13630 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
13640 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
13650 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
13660 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
13670 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
13680 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
13690 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
136a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
136b0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
136c0 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
136d0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
136e0 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
136f0 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f  set handler.  No
13700 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
13710 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
13720 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
13730 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
13740 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
13750 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
13760 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
13770 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
13780 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
13790 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
137a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
137b0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
137c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
137d0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
137e0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
137f0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
13800 72 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49  r..** .** INVARI
13810 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
13820 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  311} The [sqlite
13830 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
13840 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ,C,A)] function 
13850 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a 2a 2a  shall replace.**
13860 20 20 20 20 20 20 20 20 20 20 62 75 73 79 20 63            busy c
13870 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 20 5b  allback in the [
13880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13890 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 20 6e 65  ion] D with a ne
138a0 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  w.**          a 
138b0 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
138c0 20 43 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69   C and applicati
138d0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
138e0 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 32  A..**.** {H12312
138f0 7d 20 4e 65 77 6c 79 20 63 72 65 61 74 65 64 20  } Newly created 
13900 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13910 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68 61 76  tions] shall hav
13920 65 20 61 20 62 75 73 79 0a 2a 2a 20 20 20 20 20  e a busy.**     
13930 20 20 20 20 20 68 61 6e 64 6c 65 72 20 6f 66 20       handler of 
13940 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  NULL..**.** {H12
13950 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72  314} When two or
13960 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 73 65 20   more [database 
13970 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61  connections] sha
13980 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  re a.**         
13990 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
139a0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20  _shared_cache | 
139b0 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a  common cache],.*
139c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
139d0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
139e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
139f0 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c  nection currentl
13a00 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  y using.**      
13a10 20 20 20 20 74 68 65 20 63 61 63 68 65 20 73 68      the cache sh
13a20 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  all be invoked w
13a30 68 65 6e 20 74 68 65 20 63 61 63 68 65 20 65 6e  hen the cache en
13a40 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e  counters a lock.
13a50 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36 7d 20  .**.** {H12316} 
13a60 49 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  If a busy handle
13a70 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
13a80 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  ns zero, then th
13a90 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
13aa0 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ce.**          t
13ab0 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65  hat provoked the
13ac0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20 73   locking event s
13ad0 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  hall return [SQL
13ae0 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
13af0 20 7b 48 31 32 33 31 38 7d 20 53 51 4c 69 74 65   {H12318} SQLite
13b00 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73 20 74   shall invokes t
13b10 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
13b20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
13b30 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20  ts which.**     
13b40 20 20 20 20 20 61 72 65 20 61 20 63 6f 70 79 20       are a copy 
13b50 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20 73  of the pointer s
13b60 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 33  upplied by the 3
13b70 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
13b80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
13b90 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
13ba0 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74  r()] and a count
13bb0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
13bc0 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20  f prior.**      
13bd0 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20      invocations 
13be0 6f 66 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  of the busy hand
13bf0 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d 65  ler for the same
13c00 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a   locking event..
13c10 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
13c20 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33 31 39  S:.**.** {A12319
13c30 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  } A busy handler
13c40 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
13c50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
13c60 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
13c70 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72 65 64      or [prepared
13c80 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
13c90 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
13ca0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
13cb0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
13cc0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
13cd0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
13ce0 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
13cf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
13d00 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20   A Busy Timeout 
13d10 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34 31 30  {H12340} <S40410
13d20 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
13d30 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
13d40 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
13d50 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
13d60 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
13d70 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
13d80 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
13d90 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
13da0 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e  locked.  The han
13db0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
13dc0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
13dd0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
13de0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
13df0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
13e00 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
13e10 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 74  ed. {H12343} Aft
13e20 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  er "ms" millisec
13e30 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
13e40 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
13e50 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
13e60 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
13e70 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
13e80 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
13e90 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
13ea0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a  OERR_BLOCKED]..*
13eb0 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69  *.** Calling thi
13ec0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
13ed0 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
13ee0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
13ef0 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
13f00 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
13f10 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  lers..**.** Ther
13f20 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
13f30 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
13f40 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
13f50 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
13f60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
13f70 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  y any given mome
13f80 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
13f90 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
13fa0 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
13fb0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
13fc0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
13fd0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
13fe0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
13ff0 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
14000 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
14010 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
14020 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
14030 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  341} The [sqlite
14040 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
14050 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
14060 20 6f 76 65 72 72 69 64 65 20 61 6e 79 20 70 72   override any pr
14070 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ior.**          
14080 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
14090 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c  meout()] or [sql
140a0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
140b0 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20  r()] setting.** 
140c0 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20           on the 
140d0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
140e0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
140f0 2a 20 7b 48 31 32 33 34 33 7d 20 49 66 20 74 68  * {H12343} If th
14100 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
14110 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  to [sqlite3_busy
14120 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c  _timeout()] is l
14130 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  ess than.**     
14140 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f       or equal to
14150 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20   zero, then the 
14160 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61  busy handler sha
14170 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 20 73 6f  ll be cleared so
14180 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
14190 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74    all subsequent
141a0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20   locking events 
141b0 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75  immediately retu
141c0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
141d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 34 7d  ..**.** {H12344}
141e0 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   If the 2nd para
141f0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
14200 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
14210 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a  ] is a positive.
14220 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
14230 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73  er N, then a bus
14240 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20  y handler shall 
14250 62 65 20 73 65 74 20 74 68 61 74 20 72 65 70 65  be set that repe
14260 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20  atedly calls.** 
14270 20 20 20 20 20 20 20 20 20 74 68 65 20 78 53 6c           the xSl
14280 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20  eep() method in 
14290 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
142a0 20 7c 20 56 46 53 20 69 6e 74 65 72 66 61 63 65   | VFS interface
142b0 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20  ] until.**      
142c0 20 20 20 20 65 69 74 68 65 72 20 74 68 65 20 6c      either the l
142d0 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e  ock clears or un
142e0 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69  til the cumulati
142f0 76 65 20 73 6c 65 65 70 20 74 69 6d 65 0a 2a 2a  ve sleep time.**
14300 20 20 20 20 20 20 20 20 20 20 72 65 70 6f 72 74            report
14310 65 64 20 62 61 63 6b 20 62 79 20 78 53 6c 65 65  ed back by xSlee
14320 70 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69  p() exceeds N mi
14330 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69  lliseconds..*/.i
14340 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
14350 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
14360 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
14370 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
14380 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
14390 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
143a0 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20 3c 53  ries {H12370} <S
143b0 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66  10000>.**.** Def
143c0 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
143d0 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
143e0 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
143f0 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
14400 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
14410 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
14420 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
14430 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
14440 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
14450 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
14460 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
14470 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
14480 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
14490 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
144a0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
144b0 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
144c0 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
144d0 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
144e0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
144f0 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
14500 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
14510 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
14520 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
14530 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
14540 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
14550 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
14560 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
14570 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
14580 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
14590 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
145a0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
145b0 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
145c0 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
145d0 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
145e0 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
145f0 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
14600 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
14610 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
14620 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
14630 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
14640 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
14650 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
14660 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
14670 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
14680 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
14690 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
146a0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
146b0 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
146c0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
146d0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
146e0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
146f0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
14700 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
14710 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
14720 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
14730 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
14740 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
14750 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
14760 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
14770 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
14780 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
14790 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
147a0 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
147b0 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
147c0 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
147d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
147e0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73  ble()]..**.** As
147f0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
14800 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
14810 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
14820 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
14830 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
14840 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
14850 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
14860 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
14870 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
14880 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14890 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
148a0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
148b0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
148c0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
148d0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
148e0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
148f0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
14900 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
14910 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
14920 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
14930 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
14940 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
14950 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
14960 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
14970 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
14980 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
14990 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
149a0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
149b0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
149c0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
149d0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
149e0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
149f0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
14a00 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
14a10 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
14a20 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
14a30 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
14a40 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
14a50 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14a60 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
14a70 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
14a80 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
14a90 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14aa0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
14ab0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
14ac0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
14ad0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
14ae0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
14af0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
14b00 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
14b10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
14b20 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
14b30 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
14b40 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
14b50 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
14b60 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
14b70 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
14b80 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
14b90 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
14ba0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
14bb0 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65   It returns a re
14bc0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
14bd0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
14be0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
14bf0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
14c00 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67  fter the calling
14c10 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69   function has fi
14c20 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
14c30 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75   result, it shou
14c40 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70  ld.** pass the p
14c50 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65  ointer to the re
14c60 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71  sult table to sq
14c70 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
14c80 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
14c90 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
14ca0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
14cb0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
14cc0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
14cd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
14ce0 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
14cf0 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
14d00 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
14d10 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
14d20 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
14d30 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
14d40 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
14d50 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
14d60 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14d70 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
14d80 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
14d90 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
14da0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
14db0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14dc0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
14dd0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
14de0 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
14df0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
14e00 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
14e10 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
14e20 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
14e30 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
14e40 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
14e50 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
14e60 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
14e70 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
14e80 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
14e90 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
14ea0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
14eb0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
14ec0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
14ed0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
14ee0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
14ef0 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
14f00 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
14f10 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
14f20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
14f30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
14f40 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  code()] or [sqli
14f50 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
14f60 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
14f70 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31 7d 20  .**.** {H12371} 
14f80 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 67 65  If a [sqlite3_ge
14f90 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 6c 73  t_table()] fails
14fa0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
14fb0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  tion, then.**   
14fc0 20 20 20 20 20 20 20 69 74 20 73 68 61 6c 6c 20         it shall 
14fd0 66 72 65 65 20 74 68 65 20 72 65 73 75 6c 74 20  free the result 
14fe0 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73  table under cons
14ff0 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 20  truction, abort 
15000 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
15010 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73  query in process
15020 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 62 73 65  , skip any subse
15030 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73  quent queries, s
15040 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
15050 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 20 6f 75     *pazResult ou
15060 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20  tput pointer to 
15070 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 20  NULL and return 
15080 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
15090 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d 20 49  **.** {H12373} I
150a0 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e 20 70  f the pnColumn p
150b0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
150c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
150d0 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a  ] is not NULL.**
150e0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 61            then a
150f0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
15100 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
15110 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
15120 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  shall.**        
15130 20 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d 62    write the numb
15140 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
15150 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
15160 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
15170 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70  he query into *p
15180 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  nColumn..**.** {
15190 48 31 32 33 37 34 7d 20 49 66 20 74 68 65 20 70  H12374} If the p
151a0 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74  nRow parameter t
151b0 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  o [sqlite3_get_t
151c0 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e  able()] is not N
151d0 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
151e0 74 68 65 6e 20 61 20 73 75 63 63 65 73 73 66 75  then a successfu
151f0 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
15200 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
15210 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20  le()] shall.**  
15220 20 20 20 20 20 20 20 20 77 72 69 74 65 73 20 74          writes t
15230 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
15240 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  s in the.**     
15250 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20       result set 
15260 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 74  of the query int
15270 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20  o *pnRow..**.** 
15280 7b 48 31 32 33 37 36 7d 20 41 20 73 75 63 63 65  {H12376} A succe
15290 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
152a0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   of [sqlite3_get
152b0 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 74 20 63  _table()] that c
152c0 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20 20 20  omputes.**      
152d0 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 20 72 65      N rows of re
152e0 73 75 6c 74 20 77 69 74 68 20 43 20 63 6f 6c 75  sult with C colu
152f0 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 68 61 6c  mns per row shal
15300 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73 75 6c  l make *pazResul
15310 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  t.**          po
15320 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 61 79 20  int to an array 
15330 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 28  of pointers to (
15340 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 73 20 77  N+1)*C strings w
15350 68 65 72 65 20 74 68 65 20 66 69 72 73 74 0a 2a  here the first.*
15360 2a 20 20 20 20 20 20 20 20 20 20 43 20 73 74 72  *          C str
15370 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d 6e 20  ings are column 
15380 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 69 6e 65  names as obtaine
15390 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  d from.**       
153a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
153b0 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 74  mn_name()] and t
153c0 68 65 20 72 65 73 74 20 61 72 65 20 63 6f 6c 75  he rest are colu
153d0 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c 75 65 73  mn result values
153e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74  .**          obt
153f0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
15400 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
15410 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37  )]..**.** {H1237
15420 39 7d 20 54 68 65 20 76 61 6c 75 65 73 20 69 6e  9} The values in
15430 20 74 68 65 20 70 61 7a 52 65 73 75 6c 74 20 61   the pazResult a
15440 72 72 61 79 20 72 65 74 75 72 6e 65 64 20 62 79  rray returned by
15450 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
15460 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ble()].**       
15470 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69 6e 20     shall remain 
15480 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c 65 61  valid until clea
15490 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  red by [sqlite3_
154a0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
154b0 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20 57 68  *.** {H12382} Wh
154c0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
154d0 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61  rs during evalua
154e0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
154f0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a  _get_table()].**
15500 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66 75            the fu
15510 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74  nction shall set
15520 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f 20 4e   *pazResult to N
15530 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20 65 72  ULL, write an er
15540 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
15550 20 20 20 20 20 20 20 20 69 6e 74 6f 20 6d 65 6d          into mem
15560 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
15570 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
15580 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 20 20  c()], make.**   
15590 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 72 6d 73         **pzErrms
155a0 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20  g point to that 
155b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c 20 61  error message, a
155c0 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 20  nd return a.**  
155d0 20 20 20 20 20 20 20 20 61 70 70 72 6f 70 72 69          appropri
155e0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
155f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
15600 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
15610 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
15620 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
15630 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
15640 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
15650 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
15660 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
15670 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
15680 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
15690 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
156a0 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
156b0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
156c0 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
156d0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
156e0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
156f0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
15700 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
15710 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
15720 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
15730 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
15740 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
15750 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
15760 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
15770 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
15780 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
15790 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
157a0 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
157b0 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30  Functions {H1740
157c0 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30  0} <S70000><S200
157d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
157e0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
157f0 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  kalikes of the "
15800 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
15810 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
15820 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
15830 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
15840 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
15850 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
15860 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
15870 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
15880 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
15890 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
158a0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
158b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
158c0 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
158d0 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
158e0 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
158f0 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
15900 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
15910 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f  ree()].  Both ro
15920 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
15930 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
15940 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
15950 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
15960 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
15970 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
15980 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
15990 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
159a0 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   In sqlite3_snpr
159b0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
159c0 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
159d0 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
159e0 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
159f0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
15a00 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
15a10 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
15a20 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
15a30 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
15a40 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
15a50 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
15a60 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
15a70 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
15a80 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
15a90 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
15aa0 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
15ab0 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
15ac0 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  ().  This is an.
15ad0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
15ae0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
15af0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
15b00 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
15b10 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
15b20 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61  ibility.  Note a
15b30 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
15b40 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
15b50 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
15b60 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
15b70 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
15b80 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
15b90 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
15ba0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
15bb0 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69  buffer.  We admi
15bc0 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
15bd0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
15be0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
15bf0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
15c00 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
15c10 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
15c20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
15c30 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
15c40 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
15c50 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
15c60 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
15c70 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  ility..**.** As 
15c80 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
15c90 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
15ca0 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
15cb0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
15cc0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
15cd0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
15ce0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
15cf0 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66  rminated.  The f
15d00 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
15d10 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
15d20 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
15d30 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
15d40 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
15d50 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
15d60 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
15d70 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
15d80 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
15d90 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
15da0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
15db0 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  rs..**.** These 
15dc0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
15dd0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
15de0 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
15df0 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
15e00 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
15e10 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
15e20 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
15e30 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
15e40 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
15e50 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
15e60 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
15e70 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
15e80 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
15e90 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
15ea0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70  .**.** The %q op
15eb0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
15ec0 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
15ed0 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
15ee0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
15ef0 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
15f00 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
15f10 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
15f20 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
15f30 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
15f40 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
15f50 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
15f60 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20  ng literal.  By 
15f70 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
15f80 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
15f90 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
15fa0 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
15fb0 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
15fc0 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
15fd0 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
15fe0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
15ff0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
16000 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
16010 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
16020 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
16030 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
16040 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
16050 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
16060 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
16070 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
16080 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
16090 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
160a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
160b0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
160c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
160d0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
160e0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
160f0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
16100 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
16110 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
16120 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
16130 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
16140 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
16150 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
16160 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
16170 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
16180 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
16190 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
161a0 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
161b0 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
161c0 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
161d0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
161e0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
161f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
16200 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
16210 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
16220 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
16230 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
16240 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
16250 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
16260 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
16270 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
16280 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
16290 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
162a0 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
162b0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
162c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
162d0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
162e0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
162f0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
16300 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
16310 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
16320 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
16330 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
16340 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
16350 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
16360 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
16370 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
16380 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
16390 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
163a0 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
163b0 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25  ral..**.** The %
163c0 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
163d0 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
163e0 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
163f0 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
16400 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
16410 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
16420 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
16430 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
16440 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
16450 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
16460 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
16470 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
16480 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
16490 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
164a0 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63   quotes) in plac
164b0 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69  e of the %Q opti
164c0 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  on.  So, for exa
164d0 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
164e0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
164f0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
16500 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
16510 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
16520 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
16530 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
16540 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
16550 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
16560 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
16570 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
16580 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
16590 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
165a0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
165b0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
165c0 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
165d0 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
165e0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
165f0 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
16600 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
16610 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
16620 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
16630 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
16640 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73  exactly like "%s
16650 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  " with the.** ad
16660 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
16670 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
16680 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
16690 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
166a0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
166b0 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
166c0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
166d0 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a  t string. {END}.
166e0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
166f0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 33 7d  :.**.** {H17403}
16700 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
16710 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73  printf()] and [s
16720 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
16730 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
16740 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
16750 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72  n either pointer
16760 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
16770 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
16780 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20  gs held in.**   
16790 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f          memory o
167a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
167b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
167c0 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  or NULL pointers
167d0 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
167e0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
167f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61  te3_malloc()] fa
16800 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34  ils..**.** {H174
16810 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  06}  The [sqlite
16820 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e  3_snprintf()] in
16830 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 61  terface writes a
16840 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
16850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55 54  .**           UT
16860 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20  F-8 string into 
16870 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74  the buffer point
16880 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ed to by the sec
16890 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
168a0 20 20 20 20 20 20 20 20 20 20 20 70 72 6f 76 69             provi
168b0 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69 72  ded that the fir
168c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
168d0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
168e0 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 37  o..**.** {H17407
168f0 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
16900 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  snprintf()] inte
16910 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77  rface does not w
16920 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a  rite slots of.**
16930 20 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6f             its o
16940 75 74 70 75 74 20 62 75 66 66 65 72 20 28 74 68  utput buffer (th
16950 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16960 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 65 20  er) outside the 
16970 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  range.**        
16980 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20     of 0 through 
16990 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73 20  N-1 (where N is 
169a0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
169b0 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  ter).**         
169c0 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20    regardless of 
169d0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
169e0 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  e string.**     
169f0 20 20 20 20 20 20 72 65 71 75 65 73 74 65 64 20        requested 
16a00 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70  by the format sp
16a10 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a  ecification..*/.
16a20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
16a30 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
16a40 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
16a50 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
16a60 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
16a70 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
16a80 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
16a90 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
16aa0 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  r*, ...);../*.**
16ab0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
16ac0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
16ad0 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30 7d 20  system {H17300} 
16ae0 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20000>.**.** T
16af0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20  he SQLite core  
16b00 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
16b10 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
16b20 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
16b30 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
16b40 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
16b50 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
16b60 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
16b70 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
16b80 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
16b90 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
16ba0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
16bb0 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
16bc0 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
16bd0 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
16be0 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
16bf0 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
16c00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
16c10 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
16c20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
16c30 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
16c40 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
16c50 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
16c60 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
16c70 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
16c80 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  ** If sqlite3_ma
16c90 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
16ca0 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
16cb0 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
16cc0 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
16cd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
16ce0 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74    If the paramet
16cf0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
16d00 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
16d10 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
16d20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
16d30 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
16d40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
16d50 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73  .**.** Calling s
16d60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
16d70 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
16d80 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
16d90 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
16da0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
16db0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
16dc0 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
16dd0 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
16de0 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
16df0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72    The sqlite3_fr
16e00 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
16e10 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
16e20 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
16e30 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
16e40 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
16e50 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
16e60 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
16e70 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
16e80 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
16e90 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
16ea0 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
16eb0 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
16ec0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
16ed0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
16ee0 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
16ef0 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
16f00 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
16f10 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
16f20 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
16f30 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
16f40 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
16f50 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
16f60 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
16f70 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
16f80 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
16f90 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
16fa0 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
16fb0 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
16fc0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
16fd0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
16fe0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  alloc()..**.** T
16ff0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
17000 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
17010 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
17020 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
17030 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
17040 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
17050 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
17060 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
17070 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
17080 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
17090 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
170a0 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
170b0 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74  parameter.  If t
170c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
170d0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
170e0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
170f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
17100 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
17110 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
17120 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
17130 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
17140 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
17150 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
17160 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17170 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f  ..** If the seco
17180 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
17190 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
171a0 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
171b0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
171c0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
171d0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
171e0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
171f0 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
17200 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
17210 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
17220 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17230 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  ..** sqlite3_rea
17240 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
17250 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
17260 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
17270 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
17280 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
17290 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
172a0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
172b0 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49  navailable..** I
172c0 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
172d0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
172e0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
172f0 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
17300 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
17310 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
17320 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
17330 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
17340 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
17350 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17360 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
17370 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
17380 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  ed..** If sqlite
17390 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
173a0 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
173b0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
173c0 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
173d0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  eed..**.** The m
173e0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
173f0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
17400 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
17410 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
17420 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
17430 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
17440 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45  yte boundary. {E
17450 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  ND}.**.** The de
17460 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61  fault implementa
17470 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f  tion of the memo
17480 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
17490 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20  bsystem uses.** 
174a0 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  the malloc(), re
174b0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
174c0 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  () provided by t
174d0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
174e0 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38  brary..** {H1738
174f0 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53  2} However, if S
17500 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
17510 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
17520 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45  LITE_MEMORY_SIZE
17530 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72  =<i>NNN</i> C pr
17540 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
17550 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f   (where <i>NNN</
17560 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65  i>.** is an inte
17570 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74  ger), then SQLit
17580 65 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69  e create a stati
17590 63 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65  c array of at le
175a0 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69  ast.** <i>NNN</i
175b0 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  > bytes in size 
175c0 61 6e 64 20 75 73 65 73 20 74 68 61 74 20 61 72  and uses that ar
175d0 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  ray for all of i
175e0 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65  ts dynamic.** me
175f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
17600 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64  needs. {END}  Ad
17610 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20  ditional memory 
17620 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e  allocator option
17630 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65  s.** may be adde
17640 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
17650 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  ases..**.** In S
17660 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
17670 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
17680 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
17690 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
176a0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
176b0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
176c0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
176d0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
176e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
176f0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
17700 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
17710 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
17720 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
17730 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
17740 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
17750 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
17760 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  be used..**.** T
17770 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
17780 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
17790 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  lls.** the syste
177a0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
177b0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
177c0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
177d0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
177e0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
177f0 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
17800 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
17810 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
17820 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
17830 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
17840 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
17850 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
17860 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
17870 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65  rors are detecte
17880 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61  d, but.** they a
17890 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
178a0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
178b0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
178c0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
178d0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
178e0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  OMEM]..**.** INV
178f0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
17900 48 31 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71  H17303}  The [sq
17910 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
17920 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
17930 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e  ns either a poin
17940 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
17950 20 20 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63      a newly chec
17960 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66  ked-out block of
17970 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
17980 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  s of memory.**  
17990 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73           that is
179a0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c   8-byte aligned,
179b0 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e   or it returns N
179c0 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61  ULL if it is una
179d0 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
179e0 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20   to fulfill the 
179f0 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b  request..**.** {
17a00 48 31 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71  H17304}  The [sq
17a10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
17a20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
17a30 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
17a40 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r if.**         
17a50 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e    N is less than
17a60 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
17a70 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 35  o..**.** {H17305
17a80 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
17a90 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61  free(P)] interfa
17aa0 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f  ce releases memo
17ab0 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  ry previously.**
17ac0 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
17ad0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
17ae0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
17af0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17b00 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
17b10 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c   making it avail
17b20 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a  able for reuse..
17b30 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 36 7d 20 20  **.** {H17306}  
17b40 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
17b50 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69  e3_free(NULL)] i
17b60 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
17b70 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31  op..**.** {H1731
17b80 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  0}  A call to [s
17b90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30  qlite3_realloc(0
17ba0 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65  ,N)] is equivale
17bb0 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20  nt to a call.** 
17bc0 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71            to [sq
17bd0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
17be0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 32 7d  ..**.** {H17312}
17bf0 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
17c00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30  ite3_realloc(P,0
17c10 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  )] is equivalent
17c20 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20   to a call.**   
17c30 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69          to [sqli
17c40 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a  te3_free(P)]..**
17c50 0a 2a 2a 20 7b 48 31 37 33 31 35 7d 20 20 54 68  .** {H17315}  Th
17c60 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
17c70 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  es [sqlite3_mall
17c80 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
17c90 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20  realloc()],.**  
17ca0 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71           and [sq
17cb0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f  lite3_free()] fo
17cc0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d  r all of its mem
17cd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ory allocation a
17ce0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  nd.**           
17cf0 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  deallocation nee
17d00 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31  ds..**.** {H1731
17d10 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  8}  The [sqlite3
17d20 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69  _realloc(P,N)] i
17d30 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
17d40 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65   either a pointe
17d50 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  r.**           t
17d60 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65  o a block of che
17d70 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20  cked-out memory 
17d80 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
17d90 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20  tes in size.**  
17da0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73           that is
17db0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c   8-byte aligned,
17dc0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
17dd0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32  er..**.** {H1732
17de0 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  1}  When [sqlite
17df0 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20  3_realloc(P,N)] 
17e00 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55  returns a non-NU
17e10 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66  LL pointer, it f
17e20 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  irst.**         
17e30 20 20 63 6f 70 69 65 73 20 74 68 65 20 66 69 72    copies the fir
17e40 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f  st K bytes of co
17e50 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74  ntent from P int
17e60 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20  o the newly.**  
17e70 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74           allocat
17e80 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20  ed block, where 
17e90 4b 20 69 73 20 74 68 65 20 6c 65 73 73 65 72 20  K is the lesser 
17ea0 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a  of N and the siz
17eb0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
17ec0 20 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a    the buffer P..
17ed0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 32 7d 20 20  **.** {H17322}  
17ee0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  When [sqlite3_re
17ef0 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75  alloc(P,N)] retu
17f00 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  rns a non-NULL p
17f10 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74  ointer, it first
17f20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
17f30 6c 65 61 73 65 73 20 74 68 65 20 62 75 66 66 65  leases the buffe
17f40 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  r P..**.** {H173
17f50 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74  23}  When [sqlit
17f60 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
17f70 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
17f80 68 65 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a  he buffer P is.*
17f90 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20  *           not 
17fa0 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65  modified or rele
17fb0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  ased..**.** ASSU
17fc0 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
17fd0 41 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69  A17350}  The poi
17fe0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
17ff0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
18000 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
18010 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20  realloc()].**   
18020 20 20 20 20 20 20 20 20 6d 75 73 74 20 62 65 20          must be 
18030 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
18040 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
18050 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
18060 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
18070 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
18080 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18090 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
180a0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
180b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e  e.**           n
180c0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
180d0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37  ased..**.** {A17
180e0 33 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63  351}  The applic
180f0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
18100 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
18110 20 70 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20   part of.**     
18120 20 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66        a block of
18130 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
18140 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
18150 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
18160 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66        [sqlite3_f
18170 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
18180 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
18190 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
181a0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
181b0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
181c0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
181d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
181e0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
181f0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
18200 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
18210 69 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20  istics {H17370} 
18220 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53  <S30210>.**.** S
18230 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
18240 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
18250 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
18260 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
18270 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
18280 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
18290 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
182a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
182b0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
182c0 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
182d0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
182e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
182f0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
18300 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
18310 2a 20 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b  * {H17371} The [
18320 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
18330 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
18340 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
18350 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20  r of bytes.**   
18360 20 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79         of memory
18370 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
18380 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
18390 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
183a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20  .**.** {H17373} 
183b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
183c0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
183d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
183e0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
183f0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
18400 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
18410 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
18420 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
18430 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ark.**          
18440 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a  was last reset..
18450 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54  **.** {H17374} T
18460 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
18470 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
18480 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
18490 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
184a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
184b0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
184c0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
184d0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65  **          adde
184e0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
184f0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
18500 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
18510 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  lloc()],.**     
18520 20 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65       but not ove
18530 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
18540 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
18550 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
18560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75  .**          rou
18570 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
18580 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
18590 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  y call..**.** {H
185a0 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72  17375} The memor
185b0 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
185c0 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
185d0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
185e0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  of.**          [
185f0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
18600 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
18610 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
18620 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
18630 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f     [sqlite3_memo
18640 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
18650 69 73 20 74 72 75 65 2e 20 20 54 68 65 20 76 61  is true.  The va
18660 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
18670 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c           by [sql
18680 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
18690 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
186a0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
186b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69  .**          pri
186c0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
186d0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
186e0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
186f0 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
18700 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
18710 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
18720 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
18730 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
18740 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
18750 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
18760 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32  tor {H17390} <S2
18770 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  0000>.**.** SQLi
18780 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
18790 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
187a0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
187b0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
187c0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
187d0 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
187e0 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
187f0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
18800 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
18810 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
18820 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
18830 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
18840 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
18850 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
18860 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
18870 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
18880 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
18890 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
188a0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
188b0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
188c0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
188d0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
188e0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
188f0 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  ** A call to thi
18900 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
18910 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
18920 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
18930 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er P..**.** The 
18940 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
18950 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
18960 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
18970 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
18980 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
18990 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
189a0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
189b0 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
189c0 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
189d0 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
189e0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
189f0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
18a00 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65  .** On all subse
18a10 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
18a20 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
18a30 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
18a40 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
18a50 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
18a60 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
18a70 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
18a80 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
18a90 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  hod..**.** INVAR
18aa0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
18ab0 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  7392} The [sqlit
18ac0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c  e3_randomness(N,
18ad0 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72  P)] interface wr
18ae0 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a  ites N bytes of.
18af0 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69 67 68  **          high
18b00 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
18b10 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
18b20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69  buffer P..*/.voi
18b30 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
18b40 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
18b50 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
18b60 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
18b70 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
18b80 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32  n Callbacks {H12
18b90 35 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a  500} <S70100>.**
18ba0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
18bb0 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74   registers a aut
18bc0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18bd0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
18be0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
18bf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
18c00 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
18c10 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
18c20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
18c30 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
18c40 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
18c50 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
18c60 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
18c70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
18c80 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
18c90 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
18ca0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
18cb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
18cc0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
18cd0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
18ce0 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20    At various.** 
18cf0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
18d00 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
18d10 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
18d20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
18d30 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
18d40 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
18d50 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18d60 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
18d70 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
18d80 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
18d90 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20  e allowed.  The 
18da0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18db0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
18dc0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
18dd0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
18de0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
18df0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
18e00 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
18e10 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
18e20 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
18e30 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
18e40 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
18e50 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
18e60 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
18e70 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
18e80 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
18e90 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
18ea0 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20   error.  If the 
18eb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18ec0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
18ed0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
18ee0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
18ef0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
18f00 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
18f10 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
18f20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18f30 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
18f40 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
18f50 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
18f60 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
18f70 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
18f80 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
18f90 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
18fa0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
18fb0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
18fc0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
18fd0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
18fe0 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63   ok.  When the c
18ff0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
19000 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
19010 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
19020 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
19030 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
19040 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
19050 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
19060 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
19070 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
19080 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
19090 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
190a0 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20 61 75  nied.  If the au
190b0 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73  thorizer code is
190c0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
190d0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
190e0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
190f0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
19100 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
19110 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
19120 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
19130 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
19140 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
19150 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
19160 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
19170 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
19180 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
19190 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
191a0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
191b0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
191c0 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
191d0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
191e0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
191f0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
19200 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
19210 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
19220 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
19230 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
19240 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19250 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
19260 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
19270 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
19280 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
19290 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
192a0 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  ce. The second p
192b0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
192c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
192d0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
192e0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
192f0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
19300 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
19310 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
19320 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
19330 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
19340 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
19350 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
19360 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
19370 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
19380 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
19390 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
193a0 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
193b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
193c0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e  orized..**.** An
193d0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
193e0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
193f0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
19400 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
19410 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
19420 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
19430 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
19440 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
19450 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
19460 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
19470 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
19480 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
19490 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
194a0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
194b0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
194c0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
194d0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
194e0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
194f0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
19500 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
19510 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
19520 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
19530 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
19540 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
19550 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
19560 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
19570 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
19580 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
19590 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
195a0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
195b0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
195c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
195d0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
195e0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
195f0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
19600 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
19610 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
19620 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
19630 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
19640 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
19650 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
19660 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
19670 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
19680 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
19690 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
196a0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
196b0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
196c0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
196d0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
196e0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
196f0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
19700 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
19710 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
19720 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
19730 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
19740 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
19750 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  orizer..**.** On
19760 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
19770 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
19780 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
19790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
197a0 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
197b0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
197c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
197d0 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
197e0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
197f0 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65 20  l.  Disable the 
19800 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
19810 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
19820 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
19830 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
19840 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
19850 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
19860 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
19870 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
19880 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
19890 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
198a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
198b0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
198c0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
198d0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
198e0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
198f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
19900 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19910 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
19920 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
19930 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
19940 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
19950 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
19960 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
19970 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   When [sqlite3_p
19980 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
19990 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
199a0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
199b0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
199c0 67 68 74 20 62 65 20 72 65 70 72 65 70 61 72 65  ght be reprepare
199d0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
199e0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
199f0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
19a00 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
19a10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
19a20 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
19a30 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
19a40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19a50 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
19a60 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
19a70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19a80 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
19a90 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
19aa0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
19ab0 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
19ac0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
19ad0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
19ae0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
19af0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
19b00 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
19b10 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
19b20 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
19b30 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
19b40 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
19b50 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20 54 68  *.** {H12501} Th
19b60 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
19b70 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29  uthorizer(D,...)
19b80 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
19b90 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20  sters a.**      
19ba0 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63      authorizer c
19bb0 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74  allback with dat
19bc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19bd0 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30   D..**.** {H1250
19be0 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  2} The authorize
19bf0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
19c00 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
19c10 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20  tements are.**  
19c20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 70 61          being pa
19c30 72 73 65 65 64 20 61 6e 64 20 63 6f 6d 70 69 6c  rseed and compil
19c40 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30  ed..**.** {H1250
19c50 33 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  3} If the author
19c60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
19c70 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20  turns any value 
19c80 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  other than.**   
19c90 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
19ca0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
19cb0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
19cc0 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20  DENY], then.**  
19cd0 20 20 20 20 20 20 20 20 74 68 65 20 61 70 70 6c          the appl
19ce0 69 63 61 74 69 6f 6e 20 69 6e 74 65 72 66 61 63  ication interfac
19cf0 65 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73  e call that caus
19d00 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
19d10 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19d20 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68  llback to run sh
19d30 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  all fail with an
19d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
19d50 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f  LITE_ERROR] erro
19d60 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70  r code and an ap
19d70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
19d80 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b  message..**.** {
19d90 48 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65  H12504} When the
19da0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19db0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
19dc0 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70  LITE_OK], the op
19dd0 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  eration.**      
19de0 20 20 20 20 64 65 73 63 72 69 62 65 64 20 69 73      described is
19df0 20 70 72 6f 63 65 73 73 65 64 20 6e 6f 72 6d 61   processed norma
19e00 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  lly..**.** {H125
19e10 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74  05} When the aut
19e20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19e30 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
19e40 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20  _DENY], the.**  
19e50 20 20 20 20 20 20 20 20 61 70 70 6c 69 63 61 74          applicat
19e60 69 6f 6e 20 69 6e 74 65 72 66 61 63 65 20 63 61  ion interface ca
19e70 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 20 74  ll that caused t
19e80 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  he.**          a
19e90 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19ea0 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20  ck to run shall 
19eb0 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  fail.**         
19ec0 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45   with an [SQLITE
19ed0 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f  _ERROR] error co
19ee0 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20  de and an error 
19ef0 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20  message.**      
19f00 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74      explaining t
19f10 68 61 74 20 61 63 63 65 73 73 20 69 73 20 64 65  hat access is de
19f20 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  nied..**.** {H12
19f30 35 30 36 7d 20 49 66 20 74 68 65 20 61 75 74 68  506} If the auth
19f40 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65  orizer code (the
19f50 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
19f60 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
19f70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
19f80 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54  lback) is [SQLIT
19f90 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20  E_READ] and the 
19fa0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19fb0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ack returns.**  
19fc0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
19fd0 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68  IGNORE], then th
19fe0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
19ff0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
1a000 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ted to.**       
1a010 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c     insert a NULL
1a020 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
1a030 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
1a040 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
1a050 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ave.**          
1a060 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
1a070 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
1a080 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  n returned..**.*
1a090 2a 20 7b 48 31 32 35 30 37 7d 20 49 66 20 74 68  * {H12507} If th
1a0a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  e authorizer cod
1a0b0 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d  e (the 2nd param
1a0c0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1a0d0 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20  orizer.**       
1a0e0 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20     callback) is 
1a0f0 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74  anything other t
1a100 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  han [SQLITE_READ
1a110 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  ], then.**      
1a120 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20      a return of 
1a130 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1a140 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66  has the same eff
1a150 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44  ect as [SQLITE_D
1a160 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ENY]..**.** {H12
1a170 35 31 30 7d 20 54 68 65 20 66 69 72 73 74 20 70  510} The first p
1a180 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1a190 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1a1a0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
1a1b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1a1c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
1a1d0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1a1e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1a1f0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
1a200 0a 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54 68 65  .** {H12511} The
1a210 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a220 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1a230 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  k is an integer.
1a240 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
1a250 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1a260 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1a270 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69  cifies the parti
1a280 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20  cular action.** 
1a290 20 20 20 20 20 20 20 20 20 74 6f 20 62 65 20 61           to be a
1a2a0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1a2b0 20 7b 48 31 32 35 31 32 7d 20 54 68 65 20 74 68   {H12512} The th
1a2c0 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
1a2d0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1a2e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
1a2f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
1a300 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1a310 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1a320 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64  n.**          ad
1a330 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
1a340 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
1a350 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1a360 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32  ed..**.** {H1252
1a370 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  0} Each call to 
1a380 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1a390 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72  horizer()] overr
1a3a0 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ides.**         
1a3b0 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
1a3c0 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72  installed author
1a3d0 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  izer..**.** {H12
1a3e0 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68  521} A NULL auth
1a3f0 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61  orizer means tha
1a400 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69  t no authorizati
1a410 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  on.**          c
1a420 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1a430 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32  ed..**.** {H1252
1a440 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 61  2} The default a
1a450 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c  uthorizer is NUL
1a460 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
1a470 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1a480 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1a490 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1a4a0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1a4b0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1a4c0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1a4d0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1a4e0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1a4f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1a500 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1a510 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20   Codes {H12590} 
1a520 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12500>.**.** T
1a530 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1a540 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1a550 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1a560 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
1a570 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
1a580 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
1a590 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
1a5a0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
1a5b0 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
1a5c0 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
1a5d0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
1a5e0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
1a5f0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
1a600 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1a610 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1a620 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
1a630 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1a640 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1a650 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a660 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
1a670 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
1a680 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
1a690 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
1a6a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
1a6b0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
1a6c0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
1a6d0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
1a6e0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
1a6f0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1a700 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
1a710 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30   {H12550} <H1250
1a720 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0>.**.** The [sq
1a730 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1a740 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1a750 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1a760 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1a770 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1a780 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1a790 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1a7a0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1a7b0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1a7c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1a7d0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1a7e0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1a7f0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1a800 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1a810 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1a820 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1a830 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1a840 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1a850 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1a860 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1a870 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1a880 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1a890 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1a8a0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1a8b0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1a8c0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1a8d0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1a8e0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1a8f0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1a900 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1a910 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1a920 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1a930 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1a940 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1a950 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1a960 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
1a970 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1a980 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
1a990 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1a9a0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1a9b0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
1a9c0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
1a9d0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1a9e0 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72  le.  The 6th par
1a9f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1aa00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1aa10 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1aa20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1aa30 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1aa40 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1aa50 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1aa60 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1aa70 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1aa80 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1aa90 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1aaa0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1aab0 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e  L code..**.** IN
1aac0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1aad0 7b 48 31 32 35 35 31 7d 20 54 68 65 20 73 65 63  {H12551} The sec
1aae0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1aaf0 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
1ab00 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1ab10 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1ab20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73  izer callback] s
1ab30 68 61 6c 6c 20 62 65 20 61 6e 20 69 6e 74 65 67  hall be an integ
1ab40 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  er.**          [
1ab50 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75  SQLITE_COPY | au
1ab60 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 74  thorizer code] t
1ab70 68 61 74 20 73 70 65 63 69 66 69 65 73 20 77 68  hat specifies wh
1ab80 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  at action.**    
1ab90 20 20 20 20 20 20 69 73 20 62 65 69 6e 67 20 61        is being a
1aba0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1abb0 20 7b 48 31 32 35 35 32 7d 20 54 68 65 20 33 72   {H12552} The 3r
1abc0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1abd0 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 20  ters to the.**  
1abe0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1abf0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1ac00 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  | authorization 
1ac10 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20 20  callback].**    
1ac20 20 20 20 20 20 20 73 68 61 6c 6c 20 62 65 20 70        shall be p
1ac30 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
1ac40 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
1ac50 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  hich.**         
1ac60 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1ac70 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d  authorizer code]
1ac80 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
1ac90 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1aca0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 33 7d  ..**.** {H12553}
1acb0 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
1acc0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  er to the.**    
1acd0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
1ace0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1acf0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1ad00 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 74 68  ack] shall be th
1ad10 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e name.**       
1ad20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61     of the databa
1ad30 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61  se (example: "ma
1ad40 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63  in", "temp", etc
1ad50 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1ad60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 34 7d  ..**.** {H12554}
1ad70 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74   The 6th paramet
1ad80 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  er to the.**    
1ad90 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
1ada0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1adb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1adc0 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 74 68  ack] shall be th
1add0 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e name.**       
1ade0 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d     of the inner-
1adf0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1ae00 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1ae10 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1ae20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 63 63           the acc
1ae30 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
1ae40 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
1ae50 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
1ae60 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 20  rectly from.**  
1ae70 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 76 65          top-leve
1ae80 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1ae90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
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 20 33 72 64 20  *********** 3rd 
1aec0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1aed0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1aee0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1aef0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1af00 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1af10 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1af20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1af30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1af40 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1af50 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1af60 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1af70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1af80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1af90 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1afa0 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1afb0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1afc0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1afd0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1afe0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1aff0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1b000 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1b010 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b020 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1b030 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1b040 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1b050 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1b060 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b070 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1b080 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1b090 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1b0a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b0b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b0c0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1b0d0 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1b0e0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1b0f0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1b100 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b110 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1b120 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1b130 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1b140 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b150 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b160 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1b170 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1b180 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1b190 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b1a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b1b0 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
1b1c0 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
1b1d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1b1e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b1f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b200 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
1b210 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
1b220 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b230 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b240 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b250 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
1b260 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
1b270 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1b280 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1b290 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b2a0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
1b2b0 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
1b2c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1b2d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b2e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b2f0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
1b300 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
1b310 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1b320 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1b330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b340 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
1b350 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
1b360 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1b370 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b380 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1b390 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
1b3a0 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
1b3b0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1b3c0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1b3d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1b3e0 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
1b3f0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
1b400 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1b410 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b420 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
1b430 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
1b440 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
1b450 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1b460 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b470 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
1b480 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
1b490 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
1b4a0 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
1b4b0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
1b4c0 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
1b4d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1b4e0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1b4f0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1b500 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1b510 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
1b520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
1b530 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1b540 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b550 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b560 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
1b570 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
1b580 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1b590 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b5a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b5b0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
1b5c0 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
1b5d0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b5e0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1b5f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b600 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
1b610 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
1b620 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
1b630 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b640 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b650 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
1b660 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
1b670 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1b680 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b690 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b6a0 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
1b6b0 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
1b6c0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1b6d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b6e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b6f0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
1b700 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
1b710 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1b720 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b740 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
1b750 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
1b760 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1b770 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b780 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b790 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
1b7a0 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
1b7b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1b7c0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1b7d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b7e0 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
1b7f0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
1b800 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1b810 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1b820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1b830 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
1b840 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
1b850 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
1b860 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
1b870 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
1b880 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
1b890 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
1b8a0 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
1b8b0 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
1b8c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
1b8d0 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
1b8e0 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
1b8f0 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
1b900 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1b910 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1b920 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31  ng Functions {H1
1b930 32 32 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2280} <S60400>.*
1b940 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
1b950 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1b960 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
1b970 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
1b980 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
1b990 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
1b9a0 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
1b9b0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
1b9c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1b9d0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
1b9e0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1b9f0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1ba00 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
1ba10 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
1ba20 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
1ba30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
1ba40 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
1ba50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1ba60 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
1ba70 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20  returns a UTF-8 
1ba80 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
1ba90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1baa0 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74  ext.** as the st
1bab0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
1bac0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20  gins executing. 
1bad0 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c   Additional call
1bae0 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61  backs occur.** a
1baf0 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
1bb00 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
1bb10 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
1bb20 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
1bb30 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
1bb40 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
1bb50 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
1bb60 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a  es the trigger..
1bb70 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
1bb80 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1bb90 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1bba0 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
1bbb0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
1bbc0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
1bbd0 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70  finishes.  The p
1bbe0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
1bbf0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
1bc00 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
1bc10 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
1bc20 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
1bc30 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
1bc40 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
1bc50 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
1bc60 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   run..**.** INVA
1bc70 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
1bc80 31 32 32 38 31 7d 20 54 68 65 20 63 61 6c 6c 62  12281} The callb
1bc90 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1bca0 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
1bcb0 74 65 33 5f 74 72 61 63 65 28 29 5d 20 0a 2a 2a  te3_trace()] .**
1bcc0 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
1bcd0 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20  be invoked.**   
1bce0 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20         whenever 
1bcf0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1bd00 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f   first begins to
1bd10 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20   execute and.** 
1bd20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65           wheneve
1bd30 72 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70  r a trigger subp
1bd40 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65 67  rogram first beg
1bd50 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a  ins to run..**.*
1bd60 2a 20 7b 48 31 32 32 38 32 7d 20 45 61 63 68 20  * {H12282} Each 
1bd70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1bd80 5f 74 72 61 63 65 28 29 5d 20 73 68 61 6c 6c 20  _trace()] shall 
1bd90 6f 76 65 72 72 69 64 65 20 74 68 65 20 70 72 65  override the pre
1bda0 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20  viously.**      
1bdb0 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74      registered t
1bdc0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  race callback..*
1bdd0 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d 20 41 20  *.** {H12283} A 
1bde0 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c 62  NULL trace callb
1bdf0 61 63 6b 20 73 68 61 6c 6c 20 64 69 73 61 62 6c  ack shall disabl
1be00 65 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e tracing..**.**
1be10 20 7b 48 31 32 32 38 34 7d 20 54 68 65 20 66 69   {H12284} The fi
1be20 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1be30 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61  the trace callba
1be40 63 6b 20 73 68 61 6c 6c 20 62 65 20 61 20 63 6f  ck shall be a co
1be50 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  py of.**        
1be60 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68    the pointer wh
1be70 69 63 68 20 77 61 73 20 74 68 65 20 33 72 64 20  ich was the 3rd 
1be80 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
1be90 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a  ite3_trace()]..*
1bea0 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54 68  *.** {H12285} Th
1beb0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1bec0 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
1bed0 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20  allback is a.** 
1bee0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1bef0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1bf00 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
1bf10 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65   the original te
1bf20 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  xt.**          o
1bf30 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
1bf40 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 61  ent as it was pa
1bf50 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74  ssed into [sqlit
1bf60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1bf70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1bf80 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20  the equivalent, 
1bf90 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e  or an SQL commen
1bfa0 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  t indicating the
1bfb0 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20   beginning.**   
1bfc0 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 69 67         of a trig
1bfd0 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a  ger subprogram..
1bfe0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20 54  **.** {H12287} T
1bff0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1c000 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1c010 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66  by [sqlite3_prof
1c020 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ile()] is invoke
1c030 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  d.**          as
1c040 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
1c050 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a  ent finishes..**
1c060 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20 54 68 65  .** {H12288} The
1c070 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1c080 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
1c090 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
1c0a0 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  py of.**        
1c0b0 20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65    the 3rd parame
1c0c0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1c0d0 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  profile()]..**.*
1c0e0 2a 20 7b 48 31 32 32 38 39 7d 20 54 68 65 20 73  * {H12289} The s
1c0f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1c100 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63  to the profile c
1c110 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20  allback is a.** 
1c120 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1c130 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1c140 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61  tring that conta
1c150 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65  ins the complete
1c160 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20   text of.**     
1c170 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 74 61       the SQL sta
1c180 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73  tement as it was
1c190 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73   processed by [s
1c1a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1c1b0 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  2()].**         
1c1c0 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
1c1d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39  nt..**.** {H1229
1c1e0 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 61 72  0} The third par
1c1f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72  ameter to the pr
1c200 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69  ofile callback i
1c210 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a  s an estimate.**
1c220 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
1c230 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73   number of nanos
1c240 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63  econds of wall-c
1c250 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72  lock time requir
1c260 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ed to.**        
1c270 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74    run the SQL st
1c280 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61  atement from sta
1c290 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f  rt to finish..*/
1c2a0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
1c2b0 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
1c2c0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
1c2d0 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
1c2e0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1c2f0 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
1c300 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
1c310 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
1c320 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
1c330 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
1c340 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
1c350 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
1c360 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
1c370 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c380 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
1c390 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30  allbacks {H12910
1c3a0 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
1c3b0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f   This routine co
1c3c0 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62  nfigures a callb
1c3d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74  ack function - t
1c3e0 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63  he.** progress c
1c3f0 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69  allback - that i
1c400 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
1c410 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
1c420 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61  ng.** running ca
1c430 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1c440 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
1c450 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a  3_step()] and.**
1c460 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1c470 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d  ble()].  An exam
1c480 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
1c490 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1c4a0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
1c4b0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
1c4c0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
1c4d0 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  ** If the progre
1c4e0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
1c4f0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1c500 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
1c510 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
1c520 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
1c530 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
1c540 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
1c550 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
1c560 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
1c570 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
1c580 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1c590 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ler must not do 
1c5a0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1c5b0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1c5c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c5d0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1c5e0 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
1c5f0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
1c600 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1c610 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1c620 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c630 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1c640 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1c650 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1c660 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1c670 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1c680 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1c690 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1c6a0 2a 20 7b 48 31 32 39 31 31 7d 20 54 68 65 20 63  * {H12911} The c
1c6b0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1c6c0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1c6d0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1c6e0 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20  handler().**    
1c6f0 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64        is invoked
1c700 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
1c710 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
1c720 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20  g calls to.**   
1c730 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1c740 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  step()]..**.** {
1c750 48 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67  H12912} The prog
1c760 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73  ress callback is
1c770 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
1c780 72 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61  r every N virtua
1c790 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61  l.**          ma
1c7a0 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77  chine opcodes, w
1c7b0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
1c7c0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
1c7d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1c7e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65   [sqlite3_progre
1c7f0 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61  ss_handler()] ca
1c800 6c 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72  ll that register
1c810 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
1c820 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66  he callback.  If
1c830 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
1c840 31 2c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  1, sqlite3_progr
1c850 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a  ess_handler().**
1c860 20 20 20 20 20 20 20 20 20 20 61 63 74 73 20 61            acts a
1c870 73 20 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67  s if a NULL prog
1c880 72 65 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64  ress handler had
1c890 20 62 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e   been specified.
1c8a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20  .**.** {H12913} 
1c8b0 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  The progress cal
1c8c0 6c 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20  lback itself is 
1c8d0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
1c8e0 65 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20  e third.**      
1c8f0 20 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20      argument to 
1c900 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1c910 5f 68 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a  _handler()..**.*
1c920 2a 20 7b 48 31 32 39 31 34 7d 20 54 68 65 20 66  * {H12914} The f
1c930 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
1c940 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  o sqlite3_progre
1c950 73 73 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20  ss_handler() is 
1c960 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f  a.**          vo
1c970 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  id pointer passe
1c980 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73  d to the progres
1c990 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  s callback.**   
1c9a0 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
1c9b0 65 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20  each time it is 
1c9c0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
1c9d0 48 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c  H12915} If a cal
1c9e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
1c9f0 65 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e  ep()] results in
1ca00 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70   fewer than N op
1ca10 63 6f 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  codes.**        
1ca20 20 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64    being executed
1ca30 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  , then the progr
1ca40 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ess callback is 
1ca50 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a  never invoked..*
1ca60 2a 0a 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45 76  *.** {H12916} Ev
1ca70 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ery call to [sql
1ca80 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1ca90 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20  ndler()].**     
1caa0 20 20 20 20 20 6f 76 65 72 77 72 69 74 65 73 20       overwrites 
1cab0 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72  any previously r
1cac0 65 67 69 73 74 65 72 65 64 20 70 72 6f 67 72 65  egistered progre
1cad0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  ss handler..**.*
1cae0 2a 20 7b 48 31 32 39 31 37 7d 20 49 66 20 74 68  * {H12917} If th
1caf0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1cb00 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  er callback is N
1cb10 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67  ULL then no prog
1cb20 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ress.**         
1cb30 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f   handler is invo
1cb40 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ked..**.** {H129
1cb50 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72  18} If the progr
1cb60 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
1cb70 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74  urns a result ot
1cb80 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e  her than 0, then
1cb90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1cba0 20 62 65 68 61 76 69 6f 72 20 69 73 20 61 20 69   behavior is a i
1cbb0 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  f [sqlite3_inter
1cbc0 72 75 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e  rupt()] had been
1cbd0 20 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20   called..**     
1cbe0 20 20 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f       <S30500>.*/
1cbf0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
1cc00 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
1cc10 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
1cc20 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
1cc30 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1cc40 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
1cc50 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
1cc60 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d  nection {H12700}
1cc70 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S40200>.**.** 
1cc80 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1cc90 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
1cca0 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73  tabase file whos
1ccb0 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20  e name is given 
1ccc0 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  by the.** filena
1ccd0 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65  me argument. The
1cce0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1ccf0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
1cd00 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
1cd10 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1cd20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1cd30 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
1cd40 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1cd50 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
1cd60 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
1cd70 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61  n16(). A [databa
1cd80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1cd90 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
1cda0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
1cdb0 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
1cdc0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
1cdd0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
1cde0 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
1cdf0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
1ce00 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
1ce10 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1ce20 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1ce30 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
1ce40 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
1ce50 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
1ce60 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
1ce70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
1ce80 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65  * object. If the
1ce90 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1cea0 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
1ceb0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
1cec0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
1ced0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
1cee0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
1cef0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1cf00 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
1cf10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1cf20 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
1cf30 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
1cf40 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
1cf50 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
1cf60 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
1cf70 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
1cf80 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a   of the error..*
1cf90 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
1cfa0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
1cfb0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1cfc0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
1cfd0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1cfe0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1cff0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
1d000 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
1d010 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1d020 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
1d030 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
1d040 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
1d050 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
1d060 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
1d070 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
1d080 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
1d090 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
1d0a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1d0b0 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
1d0c0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
1d0d0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
1d0e0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
1d0f0 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
1d100 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
1d110 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1d120 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
1d130 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
1d140 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
1d150 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
1d160 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
1d170 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
1d180 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
1d190 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
1d1a0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
1d1b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
1d1c0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
1d1d0 74 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  ter can take one
1d1e0 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
1d1f0 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
1d200 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
1d210 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
1d220 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1d230 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51  _NOMUTEX] or [SQ
1d240 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1d250 54 45 58 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a  TEX] flags:.**.*
1d260 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53  * <dl>.** <dt>[S
1d270 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1d280 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
1d290 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1d2a0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
1d2b0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
1d2c0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1d2d0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
1d2e0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1d2f0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1d300 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  >.**.** <dt>[SQL
1d310 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1d320 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1d330 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1d340 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1d350 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1d360 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
1d370 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
1d380 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
1d390 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1d3a0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1d3b0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
1d3c0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
1d3d0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
1d3e0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
1d3f0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
1d400 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a   returned.</dd>.
1d410 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54  **.** <dt>[SQLIT
1d420 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1d430 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
1d440 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
1d450 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1d460 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1d470 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1d480 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
1d490 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20  tes it if.** it 
1d4a0 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
1d4b0 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
1d4c0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
1d4d0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
1d4e0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1d4f0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1d500 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
1d510 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  >.** </dl>.**.**
1d520 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
1d530 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1d540 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
1d550 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
1d560 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
1d570 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20  wn above or one 
1d580 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69  of the combinati
1d590 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
1d5a0 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68  combined.** with
1d5b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1d5c0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53  N_NOMUTEX] or [S
1d5d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1d5e0 55 54 45 58 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20  UTEX] flags,.** 
1d5f0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1d600 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
1d610 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51  **.** If the [SQ
1d620 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1d630 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
1d640 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1d650 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1d660 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
1d670 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
1d680 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
1d690 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
1d6a0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
1d6b0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
1d6c0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1d6d0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
1d6e0 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   If the.** [SQLI
1d6f0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1d700 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
1d710 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1d720 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
1d730 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
1d740 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
1d750 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
1d760 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
1d770 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1d780 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
1d790 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1d7a0 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  -time..**.** If 
1d7b0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1d7c0 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
1d7d0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1d7e0 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
1d7f0 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
1d800 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
1d810 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73  onnection.  This
1d820 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1d830 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
1d840 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
1d850 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1d860 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
1d870 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1d880 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
1d890 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
1d8a0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
1d8b0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
1d8c0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
1d8d0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
1d8e0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1d8f0 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
1d900 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
1d910 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
1d920 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
1d930 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
1d940 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
1d950 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
1d960 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
1d970 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
1d980 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
1d990 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  ** If the filena
1d9a0 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
1d9b0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
1d9c0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1d9d0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
1d9e0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1d9f0 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76  ated.  This priv
1da00 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
1da10 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
1da20 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
1da30 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
1da40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1da50 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
1da60 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
1da70 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1da80 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
1da90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1daa0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
1dab0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
1dac0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
1dad0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1dae0 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
1daf0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1db00 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
1db10 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72 74  e.  If the fourt
1db20 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1db30 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1db40 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
1db50 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1db60 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
1db70 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
1db80 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
1db90 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
1dba0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
1dbb0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1dbc0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
1dbd0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1dbe0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
1dbf0 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
1dc00 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
1dc10 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
1dc20 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
1dc30 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
1dc40 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
1dc50 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
1dc60 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
1dc70 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
1dc80 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
1dc90 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
1dca0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
1dcb0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
1dcc0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1dcd0 2a 20 7b 48 31 32 37 30 31 7d 20 54 68 65 20 5b  * {H12701} The [
1dce0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1dcf0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1dd00 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ()], and.**     
1dd10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
1dd20 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
1dd30 63 65 73 20 63 72 65 61 74 65 20 61 20 6e 65 77  ces create a new
1dd40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
1dd50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1dd60 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  n] associated wi
1dd70 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
1dd80 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
1dd90 20 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72 20   given in their 
1dda0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1ddb0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 32 7d 20  .**.** {H12702} 
1ddc0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
1ddd0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
1dde0 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a  eted as UTF-8.**
1ddf0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b 73            for [s
1de00 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61  qlite3_open()] a
1de10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
1de20 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54  _v2()] and as UT
1de30 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20  F-16.**         
1de40 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1de50 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73  yte order for [s
1de60 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1de70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 33 7d  ..**.** {H12703}
1de80 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
1de90 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1dea0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1deb0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1dec0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1ded0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1dee0 32 28 29 5d 20 77 72 69 74 65 73 20 61 20 70 6f  2()] writes a po
1def0 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a  inter to a new.*
1df00 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
1df10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1df20 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a   into *ppDb..**.
1df30 2a 2a 20 7b 48 31 32 37 30 34 7d 20 54 68 65 20  ** {H12704} The 
1df40 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1df50 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1df60 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20  6()], and.**    
1df70 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
1df80 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
1df90 61 63 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  aces return [SQL
1dfa0 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63  ITE_OK] upon suc
1dfb0 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20  cess,.**        
1dfc0 20 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69    or an appropri
1dfd0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
1dfe0 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a   on failure..**.
1dff0 2a 2a 20 7b 48 31 32 37 30 36 7d 20 54 68 65 20  ** {H12706} The 
1e000 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63  default text enc
1e010 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20  oding for a new 
1e020 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64  database created
1e030 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
1e040 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
1e050 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1e060 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20  open_v2()] will 
1e070 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  be UTF-8..**.** 
1e080 7b 48 31 32 37 30 37 7d 20 54 68 65 20 64 65 66  {H12707} The def
1e090 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69  ault text encodi
1e0a0 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74  ng for a new dat
1e0b0 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73  abase created us
1e0c0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
1e0d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1e0e0 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  )] will be UTF-1
1e0f0 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 39  6..**.** {H12709
1e100 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  } The [sqlite3_o
1e110 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72 66  pen(F,D)] interf
1e120 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ace is equivalen
1e130 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  t to.**         
1e140 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1e150 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72  2(F,D,G,0)] wher
1e160 65 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  e the G paramete
1e170 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  r is.**         
1e180 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
1e190 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45  ADWRITE]|[SQLITE
1e1a0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a  _OPEN_CREATE]..*
1e1b0 2a 0a 2a 2a 20 7b 48 31 32 37 31 31 7d 20 49 66  *.** {H12711} If
1e1c0 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
1e1d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1e1e0 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63  n_v2(F,D,G,V)] c
1e1f0 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20  ontains the.**  
1e200 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
1e210 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
1e220 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68  EADONLY] then th
1e230 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1e240 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ened.**         
1e250 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c   for reading onl
1e260 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 32  y..**.** {H12712
1e270 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1e280 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1e290 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
1e2a0 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  )] contains the.
1e2b0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
1e2c0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
1e2d0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 74 68  EN_READWRITE] th
1e2e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1e2f0 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20  is opened.**    
1e300 20 20 20 20 20 20 72 65 61 64 69 6e 67 20 61 6e        reading an
1e310 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
1e320 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65  sible, or for re
1e330 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68  ading only if th
1e340 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  e.**          fi
1e350 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
1e360 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
1e370 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a  rating system..*
1e380 2a 0a 2a 2a 20 7b 48 31 32 37 31 33 7d 20 49 66  *.** {H12713} If
1e390 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
1e3a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1e3b0 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f  n_v2(F,D,G,V)] o
1e3c0 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  mits the.**     
1e3d0 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1e3e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1e3f0 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61  TE] and the data
1e400 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1e410 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f            previo
1e420 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65  usly exist, an e
1e430 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1e440 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 34 7d  ..**.** {H12714}
1e450 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
1e460 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1e470 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
1e480 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  ] contains the.*
1e490 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76  *          bit v
1e4a0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  alue [SQLITE_OPE
1e4b0 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68  N_CREATE] and th
1e4c0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
1e4d0 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  not.**          
1e4e0 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74  previously exist
1e4f0 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70  , then an attemp
1e500 74 20 69 73 20 6d 61 64 65 20 74 6f 20 63 72 65  t is made to cre
1e510 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ate and.**      
1e520 20 20 20 20 69 6e 69 74 69 61 6c 69 7a 65 20 74      initialize t
1e530 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a  he database..**.
1e540 2a 2a 20 7b 48 31 32 37 31 37 7d 20 49 66 20 74  ** {H12717} If t
1e550 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1e560 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1e570 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1e580 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
1e590 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
1e5a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1e5b0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1e5c0 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 2c  then an private,
1e5d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68  .**          eph
1e5e0 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72  emeral, in-memor
1e5f0 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72  y database is cr
1e600 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
1e610 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20  nnection..**    
1e620 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53        <todo>Is S
1e630 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1e640 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  E|SQLITE_OPEN_RE
1e650 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64  ADWRITE required
1e660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
1e670 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1e680 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  )?</todo>.**.** 
1e690 7b 48 31 32 37 31 39 7d 20 49 66 20 74 68 65 20  {H12719} If the 
1e6a0 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c  filename is NULL
1e6b0 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72   or an empty str
1e6c0 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
1e6d0 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ate,.**         
1e6e0 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69   ephemeral on-di
1e6f0 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
1e700 20 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20   be created..** 
1e710 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49           <todo>I
1e720 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  s SQLITE_OPEN_CR
1e730 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e  EATE|SQLITE_OPEN
1e740 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69  _READWRITE requi
1e750 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
1e760 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  in sqlite3_open_
1e770 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  v2()?</todo>.**.
1e780 2a 2a 20 7b 48 31 32 37 32 31 7d 20 54 68 65 20  ** {H12721} The 
1e790 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1e7a0 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62 79  tion] created by
1e7b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1e7c0 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20  2(F,D,G,V)].**  
1e7d0 20 20 20 20 20 20 20 20 77 69 6c 6c 20 75 73 65          will use
1e7e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1e7f0 73 5d 20 6f 62 6a 65 63 74 20 69 64 65 6e 74 69  s] object identi
1e800 66 69 65 64 20 62 79 20 74 68 65 20 56 20 70 61  fied by the V pa
1e810 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20 20 20 20  rameter,.**     
1e820 20 20 20 20 20 6f 72 20 74 68 65 20 64 65 66 61       or the defa
1e830 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1e840 5d 20 6f 62 6a 65 63 74 20 69 66 20 56 20 69 73  ] object if V is
1e850 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1e860 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 33 7d 20  .**.** {H12723} 
1e870 54 77 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f  Two [database co
1e880 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20  nnections] will 
1e890 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63  share a common c
1e8a0 61 63 68 65 20 69 66 20 62 6f 74 68 20 77 65 72  ache if both wer
1e8b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70  e.**          op
1e8c0 65 6e 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ened with the sa
1e8d0 6d 65 20 56 46 53 20 77 68 69 6c 65 20 5b 73 68  me VFS while [sh
1e8e0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1e8f0 20 77 61 73 20 65 6e 61 62 6c 65 64 20 61 6e 64   was enabled and
1e900 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20  .**          if 
1e910 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65 73 20 63  both filenames c
1e920 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 75 73 69  ompare equal usi
1e930 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61 66 74 65  ng memcmp() afte
1e940 72 20 68 61 76 69 6e 67 20 62 65 65 6e 0a 2a 2a  r having been.**
1e950 20 20 20 20 20 20 20 20 20 20 70 72 6f 63 65 73            proces
1e960 73 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  sed by the [sqli
1e970 74 65 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c 50  te3_vfs | xFullP
1e980 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64 20  athname] method 
1e990 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a 2f 0a 69  of the VFS..*/.i
1e9a0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
1e9b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
1e9c0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1e9d0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1e9e0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
1e9f0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
1ea00 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1ea10 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1ea20 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1ea30 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
1ea40 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
1ea50 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1ea60 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
1ea70 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1ea80 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
1ea90 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1eaa0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
1eab0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1eac0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
1ead0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1eae0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1eaf0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
1eb00 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
1eb10 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1eb20 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1eb30 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
1eb40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
1eb50 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
1eb60 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
1eb70 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
1eb80 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
1eb90 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1eba0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
1ebb0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48   And Messages {H
1ebc0 31 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a  12800} <S60200>.
1ebd0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1ebe0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
1ebf0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1ec00 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
1ec10 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
1ec20 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1ec30 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1ec40 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
1ec50 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
1ec60 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
1ec70 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1ec80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
1ec90 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
1eca0 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
1ecb0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1ecc0 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
1ecd0 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
1ece0 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
1ecf0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1ed00 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 54  is undefined.  T
1ed10 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
1ed20 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
1ed30 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
1ed40 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
1ed50 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
1ed60 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
1ed70 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
1ed80 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
1ed90 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
1eda0 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
1edb0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  led..**.** The s
1edc0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
1edd0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
1ede0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
1edf0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
1ee00 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
1ee10 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
1ee20 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1ee30 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
1ee40 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f  ctively..** Memo
1ee50 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
1ee60 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
1ee70 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
1ee80 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
1ee90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1eea0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
1eeb0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
1eec0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
1eed0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
1eee0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
1eef0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
1ef00 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
1ef10 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
1ef20 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
1ef30 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
1ef40 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
1ef50 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
1ef60 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1ef70 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
1ef80 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
1ef90 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
1efa0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
1efb0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
1efc0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
1efd0 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
1efe0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
1eff0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
1f000 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
1f010 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
1f020 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
1f030 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
1f040 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
1f050 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
1f060 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
1f070 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
1f080 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
1f090 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
1f0a0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
1f0b0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
1f0c0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
1f0d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f0e0 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
1f0f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
1f100 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
1f110 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
1f120 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
1f130 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
1f140 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
1f150 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
1f160 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
1f170 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
1f180 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
1f190 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
1f1a0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
1f1b0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
1f1c0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
1f1d0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
1f1e0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
1f1f0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
1f200 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
1f210 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
1f220 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
1f230 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
1f240 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
1f250 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
1f260 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
1f270 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  et..**.** INVARI
1f280 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
1f290 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  801} The [sqlite
1f2a0 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e  3_errcode(D)] in
1f2b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1f2c0 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  the numeric.**  
1f2d0 20 20 20 20 20 20 20 20 5b 72 65 73 75 6c 74 20          [result 
1f2e0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
1f2f0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1f300 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
1f310 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ently.**        
1f320 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61    failed interfa
1f330 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  ce call associat
1f340 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1f350 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f360 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38  ] D..**.** {H128
1f370 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
1f380 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1f390 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(D)] interface 
1f3a0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
1f3b0 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ric.**          
1f3c0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1f3d0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
1f3e0 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20  ost recently.** 
1f3f0 20 20 20 20 20 20 20 20 20 66 61 69 6c 65 64 20           failed 
1f400 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61  interface call a
1f410 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1f420 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1f430 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
1f440 2a 20 7b 48 31 32 38 30 33 7d 20 54 68 65 20 5b  * {H12803} The [
1f450 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44  sqlite3_errmsg(D
1f460 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1f470 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20  errmsg16(D)].** 
1f480 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
1f490 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  ces return Engli
1f4a0 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
1f4b0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 0a   that describes.
1f4c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1f4d0 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73  error in the mos
1f4e0 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69  tly recently fai
1f4f0 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61  led interface ca
1f500 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ll,.**          
1f510 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74 68 65  encoded as eithe
1f520 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1f530 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
1f540 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54  **.** {H12807} T
1f550 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1f560 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1f570 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73  errmsg()] and [s
1f580 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1f590 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1f5a0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  re valid until t
1f5b0 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69  he next SQLite i
1f5c0 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a  nterface call..*
1f5d0 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43 61  *.** {H12808} Ca
1f5e0 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69  lls to API routi
1f5f0 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  nes that do not 
1f600 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20  return an error 
1f610 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
1f620 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69   (example: [sqli
1f630 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
1f640 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20  ]) do not.**    
1f650 20 20 20 20 20 20 63 68 61 6e 67 65 20 74 68 65        change the
1f660 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d   error code or m
1f670 65 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20  essage returned 
1f680 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  by.**          [
1f690 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1f6a0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  )], [sqlite3_ext
1f6b0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
1f6c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
1f6d0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1f6e0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  , or [sqlite3_er
1f6f0 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rmsg16()]..**.**
1f700 20 7b 48 31 32 38 30 39 7d 20 49 6e 74 65 72 66   {H12809} Interf
1f710 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f  aces that are no
1f720 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
1f730 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  h a specific.** 
1f740 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1f750 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
1f760 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20  examples:.**    
1f770 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
1f780 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71  printf()] or [sq
1f790 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1f7a0 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20  red_cache()].** 
1f7b0 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20           do not 
1f7c0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
1f7d0 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
1f7e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1f7f0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
1f800 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1f810 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
1f820 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1f830 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20  3_errmsg()], or 
1f840 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1f850 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
1f860 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
1f870 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
1f880 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1f890 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1f8a0 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
1f8b0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1f8c0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
1f8d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1f8e0 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
1f8f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1f900 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
1f910 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30  nt Object {H1300
1f920 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b  0} <H13010>.** K
1f930 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
1f940 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
1f950 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f960 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
1f970 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
1f980 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
1f990 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
1f9a0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
1f9b0 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
1f9c0 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
1f9d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f9e0 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
1f9f0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
1fa00 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
1fa10 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
1fa20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
1fa30 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
1fa40 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
1fa50 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
1fa60 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1fa70 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
1fa80 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1fa90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1faa0 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
1fab0 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
1fac0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
1fad0 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
1fae0 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
1faf0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1fb00 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
1fb10 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
1fb20 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
1fb30 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1fb40 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
1fb50 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
1fb60 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
1fb70 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1fb80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1fb90 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
1fba0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
1fbb0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
1fbc0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1fbd0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
1fbe0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1fbf0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1fc00 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
1fc10 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
1fc20 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
1fc30 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
1fc40 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
1fc50 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1fc60 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
1fc70 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
1fc80 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
1fc90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fca0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
1fcb0 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30  ts {H12760} <S20
1fcc0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
1fcd0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1fce0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
1fcf0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
1fd00 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
1fd10 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
1fd20 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
1fd30 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
1fd40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1fd50 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
1fd60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
1fd70 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
1fd80 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
1fd90 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1fda0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
1fdb0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
1fdc0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
1fdd0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
1fde0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
1fdf0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
1fe00 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
1fe10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1fe20 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
1fe30 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20  that construct. 
1fe40 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   The function re
1fe50 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69  turns the old li
1fe60 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  mit..**.** If th
1fe70 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
1fe80 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
1fe90 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
1fea0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72  nchanged..** For
1feb0 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67   the limit categ
1fec0 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49  ory of SQLITE_LI
1fed0 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73  MIT_XYZ there is
1fee0 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
1fef0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
1ff00 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61 20 63  d].** set by a c
1ff10 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72  ompile-time C pr
1ff20 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1ff30 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69   named .** [limi
1ff40 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
1ff50 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  XYZ]..** (The "_
1ff60 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
1ff70 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
1ff80 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41  o "_MAX_".).** A
1ff90 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1ffa0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1ffb0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1ffc0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1ffd0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1ffe0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1fff0 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20  er limit..**.** 
20000 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run time limits 
20010 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
20020 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
20030 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
20040 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
20050 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
20060 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
20070 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
20080 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
20090 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
200a0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
200b0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
200c0 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
200d0 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
200e0 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
200f0 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
20100 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
20110 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
20120 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
20130 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
20140 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
20150 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
20160 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
20170 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
20180 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
20190 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
201a0 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
201b0 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
201c0 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
201d0 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
201e0 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
201f0 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
20200 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
20210 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
20220 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
20230 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
20240 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
20250 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
20260 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
20270 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
20280 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
20290 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
202a0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
202b0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
202c0 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
202d0 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
202e0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
202f0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
20300 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
20310 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
20320 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
20330 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
20340 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
20350 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
20360 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
20370 2a 2a 20 7b 48 31 32 37 36 32 7d 20 41 20 73 75  ** {H12762} A su
20380 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
20390 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
203a0 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20  D,C,V)] where V 
203b0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  is.**          p
203c0 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65 73 20  ositive changes 
203d0 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65  the limit on the
203e0 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75   size of constru
203f0 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ct C in the.**  
20400 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
20410 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
20420 74 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66  to the lesser of
20430 20 56 20 61 6e 64 20 74 68 65 20 68 61 72 64 20   V and the hard 
20440 75 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  upper.**        
20450 20 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73    bound on the s
20460 69 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69 73  ize of C that is
20470 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
20480 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  time..**.** {H12
20490 37 36 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  766} A successfu
204a0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
204b0 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d  e3_limit(D,C,V)]
204c0 20 77 68 65 72 65 20 56 20 69 73 20 6e 65 67 61   where V is nega
204d0 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
204e0 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61 74   leaves the stat
204f0 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
20500 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
20510 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a   unchanged..**.*
20520 2a 20 7b 48 31 32 37 36 39 7d 20 41 20 73 75 63  * {H12769} A suc
20530 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
20540 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
20550 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74  ,C,V)] returns t
20560 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  he.**          v
20570 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
20580 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  t on the size of
20590 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20   construct C in 
205a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
205b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
205c0 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61  tion] D as it wa
205d0 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63  s prior to the c
205e0 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  all..*/.int sqli
205f0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
20600 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
20610 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
20620 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
20630 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
20640 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 31  ies {H12790} <H1
20650 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  2760>.** KEYWORD
20660 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
20670 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  ry} {limit categ
20680 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
20690 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
206a0 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
206b0 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
206c0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
206d0 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
206e0 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
206f0 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
20700 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
20710 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
20720 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
20730 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
20740 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
20750 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
20760 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
20770 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
20780 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
20790 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
207a0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
207b0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
207c0 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
207d0 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
207e0 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64   or table row.<d
207f0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
20800 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
20810 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
20820 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
20830 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
20840 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a  atement.</dd>.**
20850 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
20860 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
20870 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
20880 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
20890 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
208a0 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
208b0 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
208c0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
208d0 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
208e0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
208f0 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
20900 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
20910 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
20920 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  clause.</dd>.**.
20930 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
20940 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
20950 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
20960 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
20970 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
20980 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
20990 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
209a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
209b0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
209c0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
209d0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
209e0 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
209f0 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
20a00 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
20a10 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
20a20 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
20a30 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
20a40 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
20a50 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
20a60 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
20a70 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
20a80 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
20a90 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
20aa0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
20ab0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
20ac0 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
20ad0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
20ae0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
20af0 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
20b00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
20b10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
20b20 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
20b30 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
20b40 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
20b50 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
20b60 61 73 65 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ases].</dd>.**.*
20b70 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
20b80 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
20b90 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
20ba0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
20bb0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
20bc0 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
20bd0 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
20be0 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
20bf0 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  rs.</dd>.**.** <
20c00 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
20c10 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
20c20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20c30 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
20c40 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61  f variables in a
20c50 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
20c60 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62  that can.** be b
20c70 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f  ound.</dd>.** </
20c80 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
20c90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
20ca0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
20cb0 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
20cc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
20cd0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
20ce0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
20cf0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
20d00 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
20d10 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
20d20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
20d30 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
20d40 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
20d50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
20d60 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
20d70 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
20d80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
20d90 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
20da0 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
20db0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
20dc0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
20dd0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
20de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
20df0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
20e00 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
20e10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
20e20 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
20e30 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
20e40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
20e50 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
20e60 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
20e70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20e80 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
20e90 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31  QL Statement {H1
20ea0 33 30 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a  3010} <S10000>.*
20eb0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
20ec0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
20ed0 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
20ee0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
20ef0 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
20f00 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
20f10 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
20f20 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
20f30 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
20f40 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
20f50 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
20f60 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
20f70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20f80 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
20f90 61 0a 2a 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20  a.** prior call 
20fa0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
20fb0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
20fc0 65 6e 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  en_v2()] or [sql
20fd0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
20fe0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
20ff0 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
21000 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
21010 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
21020 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
21030 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
21040 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
21050 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
21060 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
21070 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
21080 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
21090 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
210a0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
210b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
210c0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
210d0 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  -16..**.** If th
210e0 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
210f0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
21100 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
21110 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
21120 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
21130 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79  rminator. If nBy
21140 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
21150 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
21160 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
21170 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
21180 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
21190 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
211a0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
211b0 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
211c0 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
211d0 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
211e0 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
211f0 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
21200 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
21210 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
21220 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
21230 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
21240 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
21250 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
21260 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
21270 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
21280 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
21290 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
212a0 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
212b0 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
212c0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
212d0 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
212e0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
212f0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
21300 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
21310 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
21320 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a  ator bytes..**.*
21330 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  * *pzTail is mad
21340 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
21350 65 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73  e first byte pas
21360 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
21370 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74  .** first SQL st
21380 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
21390 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
213a0 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68   only compile th
213b0 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65  e first.** state
213c0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
213d0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
213e0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61   pointing to wha
213f0 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63  t remains.** unc
21400 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a  ompiled..**.** *
21410 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
21420 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
21430 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
21440 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
21450 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
21460 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
21470 33 5f 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74  3_step()].  If t
21480 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
21490 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
214a0 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66  .** to NULL.  If
214b0 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
214c0 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
214d0 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
214e0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
214f0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
21500 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
21510 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
21520 2a 20 7b 41 31 33 30 31 38 7d 20 54 68 65 20 63  * {A13018} The c
21530 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65  alling procedure
21540 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
21550 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65  for deleting the
21560 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c   compiled.** SQL
21570 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
21580 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
21590 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68  ze()] after it h
215a0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
215b0 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75   it..**.** On su
215c0 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f  ccess, [SQLITE_O
215d0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20  K] is returned, 
215e0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
215f0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
21600 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
21610 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
21620 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
21630 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21640 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
21650 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
21660 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
21670 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
21680 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
21690 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
216a0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
216b0 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
216c0 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
216d0 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74  ouraged..** In t
216e0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
216f0 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
21700 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
21710 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
21720 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
21730 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
21740 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
21750 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
21760 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
21770 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
21780 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
21790 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
217a0 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  a differently in
217b0 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a   two ways:.**.**
217c0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
217d0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
217e0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
217f0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
21800 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
21810 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
21820 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
21830 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
21840 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
21850 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
21860 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
21870 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
21880 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49  run it again.  I
21890 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73  f the schema has
218a0 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61   changed in.** a
218b0 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20   way that makes 
218c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f  the statement no
218d0 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b   longer valid, [
218e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
218f0 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65  will still.** re
21900 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  turn [SQLITE_SCH
21910 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b  EMA].  But unlik
21920 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
21930 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53  avior, [SQLITE_S
21940 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77  CHEMA] is.** now
21950 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20   a fatal error. 
21960 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
21970 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21980 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
21990 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
219a0 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
219b0 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
219c0 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
219d0 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74  the text.** of t
219e0 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72  he parsing error
219f0 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
21a00 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
21a10 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c  MA] return..** <
21a20 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
21a30 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  ** When an error
21a40 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
21a50 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
21a60 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
21a70 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
21a80 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
21a90 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
21aa0 64 65 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63  des].  The legac
21ab0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
21ac0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
21ad0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
21ae0 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
21af0 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
21b00 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
21b10 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20  * and you would 
21b20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
21b30 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
21b40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21b50 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66  in order.** to f
21b60 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
21b70 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
21b80 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
21b90 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
21ba0 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
21bb0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
21bc0 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
21bd0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
21be0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
21bf0 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  li>.** </ol>.**.
21c00 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
21c10 2a 0a 2a 2a 20 7b 48 31 33 30 31 31 7d 20 54 68  *.** {H13011} Th
21c20 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
21c30 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  re(db,zSql,...)]
21c40 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
21c50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21c60 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  e_v2(db,zSql,...
21c70 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e  )] interfaces in
21c80 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20  terpret the.**  
21c90 20 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20          text in 
21ca0 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d  their zSql param
21cb0 65 74 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a  eter as UTF-8..*
21cc0 2a 0a 2a 2a 20 7b 48 31 33 30 31 32 7d 20 54 68  *.** {H13012} Th
21cd0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
21ce0 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  re16(db,zSql,...
21cf0 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
21d00 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
21d10 61 72 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c  are16_v2(db,zSql
21d20 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
21d30 73 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  s interpret the.
21d40 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74  **          text
21d50 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70   in their zSql p
21d60 61 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d  arameter as UTF-
21d70 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
21d80 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a   byte order..**.
21d90 2a 2a 20 7b 48 31 33 30 31 33 7d 20 49 66 20 74  ** {H13013} If t
21da0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
21db0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
21dc0 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
21dd0 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ,nByte,...)].** 
21de0 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73           and its
21df0 20 76 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73   variants is les
21e00 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
21e10 20 53 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20   SQL text is.** 
21e20 20 20 20 20 20 20 20 20 20 72 65 61 64 20 66 72           read fr
21e30 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  om zSql is read 
21e40 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
21e50 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
21e60 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 34 7d 20  .**.** {H13014} 
21e70 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
21e80 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
21e90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
21ea0 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d  zSql,nByte,...)]
21eb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
21ec0 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73   its variants is
21ed0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
21ee0 68 65 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79 74  hen at most nByt
21ef0 65 73 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20  es bytes of.**  
21f00 20 20 20 20 20 20 20 20 53 51 4c 20 74 65 78 74          SQL text
21f10 20 69 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53   is read from zS
21f20 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31  ql..**.** {H1301
21f30 35 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70  5} In [sqlite3_p
21f40 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
21f50 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61  l,N,P,pzTail)] a
21f60 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a  nd its variants.
21f70 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74  **          if t
21f80 68 65 20 7a 53 71 6c 20 69 6e 70 75 74 20 74 65  he zSql input te
21f90 78 74 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65  xt contains more
21fa0 20 74 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74   than one SQL st
21fb0 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20  atement.**      
21fc0 20 20 20 20 61 6e 64 20 70 7a 54 61 69 6c 20 69      and pzTail i
21fd0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
21fe0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
21ff0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
22000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72  .**          fir
22010 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65  st byte past the
22020 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
22030 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
22040 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20  in zSql..**     
22050 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20       <todo>What 
22060 64 6f 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69  does *pzTail poi
22070 6e 74 20 74 6f 20 69 66 20 74 68 65 72 65 20 69  nt to if there i
22080 73 20 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f  s one statement?
22090 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48  </todo>.**.** {H
220a0 31 33 30 31 36 7d 20 41 20 73 75 63 63 65 73 73  13016} A success
220b0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
220c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
220d0 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74  db,zSql,N,ppStmt
220e0 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
220f0 20 20 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73     or one of its
22100 20 76 61 72 69 61 6e 74 73 20 77 72 69 74 65 73   variants writes
22110 20 69 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61 20   into *ppStmt a 
22120 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77  pointer to a new
22130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
22140 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22150 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  ] or a pointer t
22160 6f 20 4e 55 4c 4c 20 69 66 20 7a 53 71 6c 20 63  o NULL if zSql c
22170 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20  ontains.**      
22180 20 20 20 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65      nothing othe
22190 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 63  r than whitespac
221a0 65 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a  e or comments..*
221b0 2a 0a 2a 2a 20 7b 48 31 33 30 31 39 7d 20 54 68  *.** {H13019} Th
221c0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
221d0 72 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  re_v2()] interfa
221e0 63 65 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  ce and its varia
221f0 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  nts return.**   
22200 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
22210 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  K] or an appropr
22220 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
22230 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a  ] upon failure..
22240 2a 2a 0a 2a 2a 20 7b 48 31 33 30 32 31 7d 20 42  **.** {H13021} B
22250 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70  efore [sqlite3_p
22260 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e  repare(db,zSql,n
22270 42 79 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61  Byte,ppStmt,pzTa
22280 69 6c 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20  il)] or its.**  
22290 20 20 20 20 20 20 20 20 76 61 72 69 61 6e 74 73          variants
222a0 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f   returns an erro
222b0 72 20 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  r (any value oth
222c0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
222d0 4f 4b 5d 29 2c 0a 2a 2a 20 20 20 20 20 20 20 20  OK]),.**        
222e0 20 20 74 68 65 79 20 66 69 72 73 74 20 73 65 74    they first set
222f0 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c   *ppStmt to NULL
22300 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
22310 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
22320 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
22330 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
22340 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
22350 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
22360 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
22370 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
22380 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
22390 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
223a0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
223b0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
223c0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
223d0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
223e0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
223f0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
22400 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
22410 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
22420 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
22430 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
22440 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
22450 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
22460 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
22470 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
22480 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
22490 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
224a0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
224b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
224c0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
224d0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
224e0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
224f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
22500 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
22510 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
22520 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
22530 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
22540 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
22550 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
22560 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
22570 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
22580 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
22590 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
225a0 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
225b0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
225c0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
225d0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
225e0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
225f0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
22600 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
22610 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
22620 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
22630 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
22640 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
22650 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
22660 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
22670 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
22680 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
22690 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
226a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
226b0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
226c0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
226d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
226e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
226f0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
22700 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
22710 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
22720 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
22730 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
22740 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
22750 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
22760 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
22770 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
22780 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
22790 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
227a0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
227b0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
227c0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
227d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
227e0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
227f0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
22800 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
22810 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
22820 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
22830 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
22840 6e 74 20 53 51 4c 20 7b 48 31 33 31 30 30 7d 20  nt SQL {H13100} 
22850 3c 48 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H13000>.**.** T
22860 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
22870 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
22880 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
22890 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
228a0 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
228b0 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
228c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
228d0 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
228e0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
228f0 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
22900 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
22910 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
22920 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22930 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  _v2()]..**.** IN
22940 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
22950 7b 48 31 33 31 30 31 7d 20 49 66 20 74 68 65 20  {H13101} If the 
22960 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22970 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20 74  ent] passed as t
22980 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
22990 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
229a0 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63  te3_sql()] was c
229b0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
229c0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
229d0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a  epare_v2()] or.*
229e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
229f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
22a00 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74  ()], then [sqlit
22a10 65 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e  e3_sql()] return
22a20 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  s.**          a 
22a30 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
22a40 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
22a50 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  ing containing a
22a60 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
22a70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
22a80 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  the original SQL
22a90 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
22aa0 2a 20 7b 48 31 33 31 30 32 7d 20 49 66 20 74 68  * {H13102} If th
22ab0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
22ac0 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73  ement] passed as
22ad0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
22ae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
22af0 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73  lite3_sql()] was
22b00 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
22b10 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
22b20 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a  prepare()] or.**
22b30 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
22b40 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
22b50 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   then [sqlite3_s
22b60 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 20 61 20  ql()] returns a 
22b70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
22b80 0a 2a 2a 20 7b 48 31 33 31 30 33 7d 20 54 68 65  .** {H13103} The
22b90 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64   string returned
22ba0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c   by [sqlite3_sql
22bb0 28 53 29 5d 20 69 73 20 76 61 6c 69 64 20 75 6e  (S)] is valid un
22bc0 74 69 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  til the.**      
22bd0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
22be0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 64 65  atement] S is de
22bf0 6c 65 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  leted using [sql
22c00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
22c10 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
22c20 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
22c30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
22c40 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
22c50 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
22c60 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
22c70 65 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32  ect {H15000} <S2
22c80 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
22c90 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
22ca0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
22cb0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
22cc0 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
22cd0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
22ce0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
22cf0 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
22d00 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
22d10 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
22d20 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
22d30 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
22d40 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
22d50 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
22d60 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56  ues it stores. V
22d70 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
22d80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
22d90 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
22da0 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
22db0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
22dc0 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
22dd0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
22de0 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
22df0 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
22e00 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
22e10 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
22e20 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
22e30 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
22e40 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
22e50 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
22e60 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
22e70 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
22e80 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
22e90 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
22ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
22eb0 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
22ec0 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
22ed0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
22ee0 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
22ef0 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
22f00 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
22f10 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
22f20 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
22f30 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
22f40 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
22f50 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
22f60 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
22f70 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
22f80 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20  ld.  A internal 
22f90 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
22fa0 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
22fb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
22fc0 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
22fd0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
22fe0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
22ff0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
23000 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
23010 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
23020 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
23030 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
23040 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
23050 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
23060 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
23070 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
23080 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
23090 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
230a0 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
230b0 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
230c0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
230d0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
230e0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
230f0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
23100 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
23110 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
23120 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
23130 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
23140 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
23150 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
23160 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
23170 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
23180 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
23190 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
231a0 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
231b0 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
231c0 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
231d0 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
231e0 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65  n between betwee
231f0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
23200 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
23210 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
23220 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
23230 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
23240 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
23250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
23260 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
23270 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
23280 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
23290 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
232a0 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
232b0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
232c0 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
232d0 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ted..** The sqli
232e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
232f0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
23300 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
23310 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
23320 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
23330 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23340 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
23350 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
23360 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
23370 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
23380 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
23390 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
233a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
233b0 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
233c0 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
233d0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
233e0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
233f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
23400 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
23410 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
23420 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
23430 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
23440 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
23450 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
23460 74 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32  t {H16001} <S202
23470 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  00>.**.** The co
23480 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
23490 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
234a0 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
234b0 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
234c0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
234d0 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  t.  A pointer to
234e0 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
234f0 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
23500 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
23510 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
23520 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
23530 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
23540 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
23550 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
23560 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
23570 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
23580 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
23590 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
235a0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
235b0 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
235c0 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
235d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
235e0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
235f0 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
23600 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
23610 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
23620 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
23630 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
23640 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
23650 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
23660 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
23670 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
23680 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
23690 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
236a0 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
236b0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
236c0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
236d0 20 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30   {H13500} <S7030
236e0 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
236f0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
23700 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
23710 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
23720 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
23730 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
23740 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
23750 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
23760 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
23770 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69   In the SQL stri
23780 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ngs input to [sq
23790 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
237a0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
237b0 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
237c0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
237d0 64 20 62 79 20 61 20 70 61 72 61 6d 65 74 65 72  d by a parameter
237e0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   in one of these
237f0 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   forms:.**.** <u
23800 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
23810 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
23820 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
23830 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
23840 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
23850 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61  *.** In the para
23860 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77  meter forms show
23870 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61  n above NNN is a
23880 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
23890 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73  l,.** and VVV is
238a0 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69   an alpha-numeri
238b0 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  c parameter name
238c0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20  . The values of 
238d0 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
238e0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
238f0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
23900 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
23910 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
23920 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
23930 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
23940 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
23950 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
23960 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
23970 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
23980 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
23990 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
239a0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
239b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
239c0 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
239d0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
239e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
239f0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
23a00 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ts..**.** The se
23a10 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
23a20 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
23a30 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
23a40 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68  to be set..** Th
23a50 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
23a60 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
23a70 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65  index of 1.  Whe
23a80 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
23a90 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
23aa0 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
23ab0 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
23ac0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
23ad0 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
23ae0 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
23af0 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
23b00 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54  occurrence..** T
23b10 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
23b20 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
23b30 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
23b40 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
23b50 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
23b60 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
23b70 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54 68   if desired.  Th
23b80 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
23b90 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
23ba0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
23bb0 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e   NNN..** The NNN
23bc0 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
23bd0 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
23be0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
23bf0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
23c00 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
23c10 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
23c20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
23c30 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  99)..**.** The t
23c40 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
23c50 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
23c60 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
23c70 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ter..**.** In th
23c80 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
23c90 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
23ca0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
23cb0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
23cc0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
23cd0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
23ce0 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
23cf0 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
23d00 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
23d10 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
23d20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
23d30 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
23d40 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  ers..** If the f
23d50 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
23d60 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
23d70 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
23d80 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
23d90 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
23da0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
23db0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
23dc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
23dd0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
23de0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
23df0 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
23e00 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
23e10 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
23e20 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
23e30 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
23e40 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
23e50 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
23e60 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
23e70 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
23e80 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
23e90 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
23ea0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
23eb0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
23ec0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
23ed0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
23ee0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
23ef0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
23f00 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
23f10 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
23f20 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68   freed..** If th
23f30 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
23f40 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
23f50 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
23f60 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
23f70 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
23f80 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
23f90 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
23fa0 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
23fb0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
23fc0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
23fd0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  urns..**.** The 
23fe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
23ff0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
24000 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
24010 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
24020 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
24030 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62  zeroes.  A zerob
24040 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
24050 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
24060 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
24070 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
24080 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
24090 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
240a0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
240b0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
240c0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
240d0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
240e0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
240f0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
24100 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
24110 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
24120 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
24130 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
24140 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20  ..** A negative 
24150 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
24160 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
24170 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
24180 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  BLOB..**.** The 
24190 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
241a0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
241b0 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a  e called after.*
241c0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
241d0 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74  re_v2()] (and it
241e0 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b  s variants) or [
241f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
24200 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b   and.** before [
24210 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
24220 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65  .** Bindings are
24230 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
24240 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
24250 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
24260 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65  * Unbound parame
24270 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
24280 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
24290 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
242a0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
242b0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
242c0 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64   or an error cod
242d0 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67  e if.** anything
242e0 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53   goes wrong.  [S
242f0 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
24300 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
24310 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
24320 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
24330 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ge.  [SQLITE_NOM
24340 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
24350 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
24360 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  s..** [SQLITE_MI
24370 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72  SUSE] might be r
24380 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73 65  eturned if these
24390 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
243a0 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72  lled on a.** vir
243b0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61  tual machine tha
243c0 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73  t is the wrong s
243d0 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68 61  tate or which ha
243e0 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66  s already been f
243f0 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74  inalized..** Det
24400 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65  ection of misuse
24410 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20   is unreliable. 
24420 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
24430 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a  ould not depend.
24440 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53  ** on SQLITE_MIS
24450 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51  USE returns.  SQ
24460 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69  LITE_MISUSE is i
24470 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63  ntended to indic
24480 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63  ate a.** a logic
24490 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70   error in the ap
244a0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75  plication.  Futu
244b0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
244c0 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70  QLite might.** p
244d0 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61 6e  anic rather than
244e0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
244f0 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ISUSE..**.** See
24500 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
24510 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
24520 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ount()],.** [sql
24530 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
24540 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
24550 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
24560 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
24570 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
24580 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  NTS:.**.** {H135
24590 30 36 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61  06} The [SQL sta
245a0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d  tement compiler]
245b0 20 72 65 63 6f 67 6e 69 7a 65 73 20 74 6f 6b 65   recognizes toke
245c0 6e 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 0a  ns of the forms.
245d0 2a 2a 20 20 20 20 20 20 20 20 20 20 22 3f 22 2c  **          "?",
245e0 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c   "?NNN", "$VVV",
245f0 20 22 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56   ":VVV", and "@V
24600 56 56 22 20 61 73 20 53 51 4c 20 70 61 72 61 6d  VV" as SQL param
24610 65 74 65 72 73 2c 0a 2a 2a 20 20 20 20 20 20 20  eters,.**       
24620 20 20 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20     where NNN is 
24630 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20  any sequence of 
24640 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 64 69 67 69  one or more digi
24650 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ts.**          a
24660 6e 64 20 77 68 65 72 65 20 56 56 56 20 69 73 20  nd where VVV is 
24670 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20  any sequence of 
24680 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68  one or more alph
24690 61 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20  anumeric.**     
246a0 20 20 20 20 20 63 68 61 72 61 63 74 65 72 73 20       characters 
246b0 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c  or "::" optional
246c0 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61  ly followed by a
246d0 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
246e0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ng.**          n
246f0 6f 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6e  o spaces and con
24700 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 70 61  tained within pa
24710 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a  rentheses..**.**
24720 20 7b 48 31 33 35 30 39 7d 20 54 68 65 20 69 6e   {H13509} The in
24730 69 74 69 61 6c 20 76 61 6c 75 65 20 6f 66 20 61  itial value of a
24740 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
24750 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  is NULL..**.** {
24760 48 31 33 35 31 32 7d 20 54 68 65 20 69 6e 64 65  H13512} The inde
24770 78 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c 20  x of an "?" SQL 
24780 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
24790 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
247a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61 72  .**          lar
247b0 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 53 51  gest index of SQ
247c0 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  L parameter to t
247d0 68 65 20 6c 65 66 74 2c 20 6f 72 20 31 20 69 66  he left, or 1 if
247e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
247f0 20 22 3f 22 20 69 73 20 74 68 65 20 6c 65 66 74   "?" is the left
24800 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
24810 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31  er..**.** {H1351
24820 35 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20  5} The index of 
24830 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61  an "?NNN" SQL pa
24840 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 69  rameter is the i
24850 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a  nteger NNN..**.*
24860 2a 20 7b 48 31 33 35 31 38 7d 20 54 68 65 20 69  * {H13518} The i
24870 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 56 56  ndex of an ":VVV
24880 22 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 22 40  ", "$VVV", or "@
24890 56 56 56 22 20 53 51 4c 20 70 61 72 61 6d 65 74  VVV" SQL paramet
248a0 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  er is.**        
248b0 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68    the same as th
248c0 65 20 69 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d  e index of leftm
248d0 6f 73 74 20 6f 63 63 75 72 72 65 6e 63 65 73 20  ost occurrences 
248e0 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  of the same.**  
248f0 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
24900 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74  r, or one more t
24910 68 61 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20  han the largest 
24920 69 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a  index over all.*
24930 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
24940 65 74 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66  eters to the lef
24950 74 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65  t if this is the
24960 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
24970 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
24980 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c   this parameter,
24990 20 6f 72 20 31 20 69 66 20 74 68 69 73 20 69 73   or 1 if this is
249a0 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61   the leftmost pa
249b0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
249c0 48 31 33 35 32 31 7d 20 54 68 65 20 5b 53 51 4c  H13521} The [SQL
249d0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
249e0 6c 65 72 5d 20 66 61 69 6c 73 20 77 69 74 68 20  ler] fails with 
249f0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  an [SQLITE_RANGE
24a00 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72  ].**          er
24a10 72 6f 72 20 69 66 20 74 68 65 20 69 6e 64 65 78  ror if the index
24a20 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
24a30 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
24a40 6e 20 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  n 1.**          
24a50 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
24a60 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
24a70 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49   SQLITE_MAX_VARI
24a80 41 42 4c 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20  ABLE_NUMBER.**  
24a90 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
24aa0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 34  r..**.** {H13524
24ab0 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  } Calls to [sqli
24ac0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
24ad0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e  sqlite3_bind(S,N
24ae0 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,V,...)].**     
24af0 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 20 74       associate t
24b00 68 65 20 76 61 6c 75 65 20 56 20 77 69 74 68 20  he value V with 
24b10 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65  all SQL paramete
24b20 72 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20  rs having an.** 
24b30 20 20 20 20 20 20 20 20 20 69 6e 64 65 78 20 6f           index o
24b40 66 20 4e 20 69 6e 20 74 68 65 20 5b 70 72 65 70  f N in the [prep
24b50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24b60 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 37  S..**.** {H13527
24b70 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  } Calls to [sqli
24b80 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
24b90 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e  sqlite3_bind(S,N
24ba0 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
24bb0 20 20 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f     override prio
24bc0 72 20 63 61 6c 6c 73 20 77 69 74 68 20 74 68 65  r calls with the
24bd0 20 73 61 6d 65 20 76 61 6c 75 65 73 20 6f 66 20   same values of 
24be0 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  S and N..**.** {
24bf0 48 31 33 35 33 30 7d 20 42 69 6e 64 69 6e 67 73  H13530} Bindings
24c00 20 65 73 74 61 62 6c 69 73 68 65 64 20 62 79 20   established by 
24c10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
24c20 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
24c30 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  d(S,...)].**    
24c40 20 20 20 20 20 20 70 65 72 73 69 73 74 20 61 63        persist ac
24c50 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73  ross calls to [s
24c60 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
24c70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 33 7d  ..**.** {H13533}
24c80 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
24c90 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
24ca0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
24cb0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
24cc0 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
24cd0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
24ce0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
24cf0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
24d00 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20  ,V,L,D)] SQLite 
24d10 62 69 6e 64 73 20 74 68 65 20 66 69 72 73 74 20  binds the first 
24d20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79  L.**          by
24d30 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  tes of the BLOB 
24d40 6f 72 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  or string pointe
24d50 64 20 74 6f 20 62 79 20 56 2c 20 77 68 65 6e 20  d to by V, when 
24d60 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  L.**          is
24d70 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
24d80 2a 0a 2a 2a 20 7b 48 31 33 35 33 36 7d 20 49 6e  *.** {H13536} In
24d90 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
24da0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
24db0 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20  ,V,L,D)] or.**  
24dc0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
24dd0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
24de0 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20  ,V,L,D)] SQLite 
24df0 62 69 6e 64 73 20 63 68 61 72 61 63 74 65 72 73  binds characters
24e00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f  .**          fro
24e10 6d 20 56 20 74 68 72 6f 75 67 68 20 74 68 65 20  m V through the 
24e20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
24e30 63 74 65 72 20 77 68 65 6e 20 4c 20 69 73 20 6e  cter when L is n
24e40 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
24e50 48 31 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73  H13539} In calls
24e60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
24e70 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
24e80 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
24e90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
24ea0 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
24eb0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
24ec0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
24ed0 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
24ee0 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70  when D is the sp
24ef0 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  ecial.**        
24f00 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49    constant [SQLI
24f10 54 45 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c 69  TE_STATIC], SQLi
24f20 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
24f30 74 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20  the value V.**  
24f40 20 20 20 20 20 20 20 20 69 73 20 68 65 6c 64 20          is held 
24f50 69 6e 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61  in static unmana
24f60 67 65 64 20 73 70 61 63 65 20 74 68 61 74 20 77  ged space that w
24f70 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a  ill not change.*
24f80 2a 20 20 20 20 20 20 20 20 20 20 64 75 72 69 6e  *          durin
24f90 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
24fa0 66 20 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a  f the binding..*
24fb0 2a 0a 2a 2a 20 7b 48 31 33 35 34 32 7d 20 49 6e  *.** {H13542} In
24fc0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
24fd0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
24fe0 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
24ff0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
25000 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
25010 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
25020 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
25030 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
25040 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20  L,D)] when D is 
25050 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20  the special.**  
25060 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74          constant
25070 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
25080 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e 65  NT], the routine
25090 20 6d 61 6b 65 73 20 61 0a 2a 2a 20 20 20 20 20   makes a.**     
250a0 20 20 20 20 20 70 72 69 76 61 74 65 20 63 6f 70       private cop
250b0 79 20 6f 66 20 74 68 65 20 76 61 6c 75 65 20 56  y of the value V
250c0 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
250d0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34  ns..**.** {H1354
250e0 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  5} In calls to [
250f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25100 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a  b(S,N,V,L,D)],.*
25110 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
25120 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
25130 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  N,V,L,D)], or.**
25140 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
25150 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
25160 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20  ,N,V,L,D)] when 
25170 44 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  D is a pointer t
25180 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  o.**          a 
25190 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65  function, SQLite
251a0 20 69 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75   invokes that fu
251b0 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f  nction to destro
251c0 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
251d0 20 20 76 61 6c 75 65 20 56 20 61 66 74 65 72 20    value V after 
251e0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
251f0 75 73 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20  using the value 
25200 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 38  V..**.** {H13548
25210 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
25220 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
25230 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74  blob(S,N,V,L)] t
25240 68 65 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a  he value bound.*
25250 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 61 20  *          is a 
25260 42 4c 4f 42 20 6f 66 20 4c 20 62 79 74 65 73 2c  BLOB of L bytes,
25270 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   or a zero-lengt
25280 68 20 42 4c 4f 42 20 69 66 20 4c 20 69 73 20 6e  h BLOB if L is n
25290 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
252a0 48 31 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73  H13551} In calls
252b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
252c0 64 5f 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20  d_value(S,N,V)] 
252d0 74 68 65 20 56 20 61 72 67 75 6d 65 6e 74 20 6d  the V argument m
252e0 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ay.**          b
252f0 65 20 65 69 74 68 65 72 20 61 20 5b 70 72 6f 74  e either a [prot
25300 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25310 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61  lue] object or a
25320 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 75  n.**          [u
25330 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
25340 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
25350 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
25360 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
25370 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
25380 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
25390 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
253a0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
253b0 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
253c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
253d0 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c  double);.int sql
253e0 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
253f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25400 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
25410 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
25420 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25430 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
25440 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
25450 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
25460 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e  _stmt*, int);.in
25470 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
25480 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
25490 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
254a0 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  ar*, int n, void
254b0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
254c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
254d0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
254e0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
254f0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
25500 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
25510 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
25520 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
25530 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
25540 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
25550 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
25560 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
25570 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
25580 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
25590 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
255a0 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48  QL Parameters {H
255b0 31 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13600} <S70300>.
255c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
255d0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
255e0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
255f0 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
25600 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
25610 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25620 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
25630 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
25640 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
25650 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
25660 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
25670 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
25680 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
25690 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
256a0 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
256b0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
256c0 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
256d0 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
256e0 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54  er time..**.** T
256f0 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
25700 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
25710 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
25720 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
25730 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
25740 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
25750 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
25760 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
25770 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
25780 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
25790 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
257a0 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
257b0 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  N are used,.** t
257c0 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
257d0 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a   in the list..**
257e0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
257f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25800 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
25810 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
25820 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
25830 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
25840 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25850 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
25860 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
25870 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 30 31 7d 20  .**.** {H13601} 
25880 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
25890 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
258a0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
258b0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
258c0 20 20 20 20 74 68 65 20 6c 61 72 67 65 73 74 20      the largest 
258d0 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c  index of all SQL
258e0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74   parameters in t
258f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
25900 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25910 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53  nt] S, or 0 if S
25920 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
25930 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
25940 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
25950 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
25960 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
25970 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25980 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
25990 20 50 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36   Parameter {H136
259a0 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  20} <S70300>.**.
259b0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
259c0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
259d0 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66  r to the name of
259e0 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51   the n-th.** [SQ
259f0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
25a00 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
25a10 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70  ement]..** SQL p
25a20 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
25a30 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
25a40 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
25a50 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
25a60 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
25a70 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
25a80 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
25a90 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
25aa0 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
25ab0 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
25ac0 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
25ad0 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
25ae0 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
25af0 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
25b00 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a  rt of the name..
25b10 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66  ** Parameters of
25b20 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
25b30 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
25b40 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
25b50 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
25b60 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20  e also referred 
25b70 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73  to as "anonymous
25b80 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
25b90 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f  .** The first ho
25ba0 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
25bb0 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
25bc0 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  not 0..**.** If 
25bd0 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f  the value n is o
25be0 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
25bf0 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d  f the n-th param
25c00 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
25c10 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
25c20 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
25c30 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
25c40 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
25c50 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
25c60 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
25c70 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
25c80 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
25c90 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
25ca0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
25cb0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
25cc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25cd0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
25ce0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
25cf0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
25d00 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
25d10 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
25d20 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
25d30 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
25d40 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25d50 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
25d60 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
25d70 2a 0a 2a 2a 20 7b 48 31 33 36 32 31 7d 20 54 68  *.** {H13621} Th
25d80 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
25d90 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53  parameter_name(S
25da0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
25db0 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
25dc0 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65     a UTF-8 rende
25dd0 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d 65  ring of the name
25de0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
25df0 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20  meter in.**     
25e00 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72       the [prepar
25e10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25e20 68 61 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20  having index N, 
25e30 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  or.**          N
25e40 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20  ULL if there is 
25e50 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  no SQL parameter
25e60 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72   with index N or
25e70 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   if the.**      
25e80 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 77 69      parameter wi
25e90 74 68 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e  th index N is an
25ea0 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d   anonymous param
25eb0 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e  eter "?"..*/.con
25ec0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
25ed0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25ee0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
25ef0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
25f00 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
25f10 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
25f20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
25f30 65 20 7b 48 31 33 36 34 30 7d 20 3c 53 37 30 33  e {H13640} <S703
25f40 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  00>.**.** Return
25f50 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
25f60 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
25f70 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
25f80 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
25f90 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
25fa0 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
25fb0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
25fc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
25fd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25fe0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
25ff0 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20  .  A zero.** is 
26000 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
26010 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
26020 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65  r is found.  The
26030 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
26040 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
26050 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
26060 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
26070 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
26080 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
26090 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
260a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
260b0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
260c0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
260d0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
260e0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
260f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26100 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
26110 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
26120 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
26130 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
26140 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
26150 0a 2a 2a 20 7b 48 31 33 36 34 31 7d 20 54 68 65  .** {H13641} The
26160 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26170 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53  arameter_index(S
26180 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
26190 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
261a0 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20     the index of 
261b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e  SQL parameter in
261c0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
261d0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20  tatement].**    
261e0 20 20 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61        S whose na
261f0 6d 65 20 6d 61 74 63 68 65 73 20 74 68 65 20 55  me matches the U
26200 54 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f  TF-8 string N, o
26210 72 20 30 20 69 66 20 74 68 65 72 65 20 69 73 0a  r 0 if there is.
26220 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d  **          no m
26230 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  atch..*/.int sql
26240 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26250 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
26260 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
26270 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
26280 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
26290 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
262a0 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
262b0 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30  tatement {H13660
262c0 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
262d0 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65   Contrary to the
262e0 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
262f0 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
26300 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
26310 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
26320 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
26330 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
26340 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26350 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69  ent]..** Use thi
26360 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
26370 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
26380 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
26390 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
263a0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 36 31 7d  :.**.** {H13661}
263b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   The [sqlite3_cl
263c0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d  ear_bindings(S)]
263d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
263e0 73 20 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20 20  s all SQL.**    
263f0 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20        parameter 
26400 62 69 6e 64 69 6e 67 73 20 69 6e 20 74 68 65 20  bindings in the 
26410 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26420 65 6e 74 5d 20 53 20 62 61 63 6b 20 74 6f 20 4e  ent] S back to N
26430 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
26440 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
26450 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
26460 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26470 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
26480 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
26490 74 20 53 65 74 20 7b 48 31 33 37 31 30 7d 20 3c  t Set {H13710} <
264a0 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65  S10700>.**.** Re
264b0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
264c0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
264d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
264e0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
264f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26500 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69  ent]. This routi
26510 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
26520 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
26530 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
26540 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
26550 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
26560 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
26570 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
26580 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31  TS:.**.** {H1371
26590 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
265a0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d  column_count(S)]
265b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
265c0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
265d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
265e0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
265f0 6c 74 20 73 65 74 20 67 65 6e 65 72 61 74 65 64  lt set generated
26600 20 62 79 20 74 68 65 20 5b 70 72 65 70 61 72 65   by the [prepare
26610 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a  d statement] S,.
26620 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 30  **          or 0
26630 20 69 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67   if S does not g
26640 65 6e 65 72 61 74 65 20 61 20 72 65 73 75 6c 74  enerate a result
26650 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
26660 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
26670 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
26680 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
26690 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
266a0 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
266b0 74 20 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c  t Set {H13720} <
266c0 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
266d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
266e0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
266f0 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
26700 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
26710 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
26720 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
26730 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20  statement.  The 
26740 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
26750 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
26760 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
26770 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
26780 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
26790 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
267a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
267b0 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
267c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
267d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
267e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
267f0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
26800 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
26810 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
26820 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
26830 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
26840 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73  statement. The s
26850 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
26860 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
26870 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65   number.  The le
26880 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
26890 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
268a0 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
268b0 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
268c0 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
268d0 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
268e0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
268f0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
26900 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
26910 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
26920 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
26930 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26940 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
26950 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
26960 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
26970 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73  lumn..**.** If s
26980 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
26990 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
269a0 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
269b0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
269c0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
269d0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
269e0 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
269f0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
26a00 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
26a10 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
26a20 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * The name of a 
26a30 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
26a40 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
26a50 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
26a60 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
26a70 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
26a80 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
26a90 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
26aa0 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
26ab0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
26ac0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
26ad0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
26ae0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
26af0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
26b00 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a   to the next..**
26b10 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
26b20 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 31 7d 20 41  **.** {H13721} A
26b30 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
26b40 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  cation of the [s
26b50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
26b60 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20  me(S,N)].**     
26b70 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72       interface r
26b80 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20  eturns the name 
26b90 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  of the Nth colum
26ba0 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a  n (where 0 is.**
26bb0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 65            the le
26bc0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66  ftmost column) f
26bd0 6f 72 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  or the result se
26be0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  t of the.**     
26bf0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
26c00 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61  tatement] S as a
26c10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
26c20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
26c30 2a 0a 2a 2a 20 7b 48 31 33 37 32 33 7d 20 41 20  *.** {H13723} A 
26c40 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
26c50 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  ation of the [sq
26c60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
26c70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20  e16(S,N)].**    
26c80 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
26c90 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65  returns the name
26ca0 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   of the Nth colu
26cb0 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a  mn (where 0 is.*
26cc0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c  *          the l
26cd0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20  eftmost column) 
26ce0 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74 20 73  for the result s
26cf0 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  et of the.**    
26d00 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
26d10 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20  statement] S as 
26d20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
26d30 64 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  d UTF-16 string.
26d40 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 74  **          in t
26d50 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
26d60 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  rder..**.** {H13
26d70 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  724} The [sqlite
26d80 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
26d90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
26da0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a  lumn_name16()].*
26db0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
26dc0 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e  faces return a N
26dd0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 74  ULL pointer if t
26de0 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65 20 74  hey are unable t
26df0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  o.**          al
26e00 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
26e10 20 68 6f 6c 64 20 74 68 65 69 72 20 6e 6f 72 6d   hold their norm
26e20 61 6c 20 72 65 74 75 72 6e 20 73 74 72 69 6e 67  al return string
26e30 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 35  s..**.** {H13725
26e40 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d  } If the N param
26e50 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
26e60 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
26e70 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
26e80 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
26e90 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  n_name16(S,N)] i
26ea0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
26eb0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  then the.**     
26ec0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
26ed0 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f  return a NULL po
26ee0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  inter..**.** {H1
26ef0 33 37 32 36 7d 20 54 68 65 20 73 74 72 69 6e 67  3726} The string
26f00 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
26f10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
26f20 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20  me(S,N)] and.** 
26f30 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
26f40 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
26f50 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c 69 64 20  S,N)] are valid 
26f60 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a  until the next.*
26f70 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 20  *          call 
26f80 74 6f 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  to either routin
26f90 65 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  e with the same 
26fa0 53 20 61 6e 64 20 4e 20 70 61 72 61 6d 65 74 65  S and N paramete
26fb0 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  rs.**          o
26fc0 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
26fd0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73  _finalize(S)] is
26fe0 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b   called..**.** {
26ff0 48 31 33 37 32 37 7d 20 57 68 65 6e 20 61 20 72  H13727} When a r
27000 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
27010 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
27020 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  ment contains.**
27030 20 20 20 20 20 20 20 20 20 20 61 6e 20 41 53 20            an AS 
27040 63 6c 61 75 73 65 2c 20 74 68 65 20 6e 61 6d 65  clause, the name
27050 20 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   of that column 
27060 69 73 20 74 68 65 20 69 64 65 6e 74 69 66 69 65  is the identifie
27070 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  r.**          to
27080 20 74 68 65 20 72 69 67 68 74 20 6f 66 20 74 68   the right of th
27090 65 20 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f  e AS keyword..*/
270a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
270b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
270c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
270d0 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
270e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
270f0 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
27100 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
27110 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27120 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
27130 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
27140 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30  lt {H13740} <S10
27150 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  700>.**.** These
27160 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64   routines provid
27170 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74  e a means to det
27180 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75  ermine what colu
27190 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61  mn of what.** ta
271a0 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61 74  ble in which dat
271b0 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f  abase a result o
271c0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
271d0 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f  tement comes fro
271e0 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  m..** The name o
271f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
27200 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
27210 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
27220 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
27230 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
27240 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64   string.  The _d
27250 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
27260 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
27270 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
27280 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
27290 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
272a0 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
272b0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
272c0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
272d0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
272e0 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
272f0 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
27300 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
27310 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
27320 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
27330 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
27340 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
27350 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
27360 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
27370 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
27380 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
27390 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ding..**.** The 
273a0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
273b0 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
273c0 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
273d0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
273e0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
273f0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  column..**.** Th
27400 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
27410 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   to the followin
27420 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72  g calls is a [pr
27430 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27440 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  ]..** These func
27450 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
27460 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
27470 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
27480 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
27490 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
274a0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
274b0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
274c0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ent..**.** If th
274d0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
274e0 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
274f0 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
27500 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
27510 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
27520 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
27530 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
27540 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
27550 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54  turn.** NULL.  T
27560 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
27570 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
27580 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
27590 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
275a0 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68  .** occurs.  Oth
275b0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
275c0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
275d0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
275e0 61 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20  abase, table.** 
275f0 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  and column that 
27600 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
27610 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
27620 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73  d from..**.** As
27630 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
27640 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
27650 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74  se postfixed wit
27660 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
27670 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
27680 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68  strings, the oth
27690 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
276a0 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d  urn UTF-8. {END}
276b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49  .**.** These API
276c0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
276d0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
276e0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
276f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
27700 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
27710 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
27720 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
27730 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ol defined..**.*
27740 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66  * {A13751}.** If
27750 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
27760 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
27770 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
27780 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
27790 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
277a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
277b0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
277c0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
277d0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
277e0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
277f0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
27800 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 31 7d 20 54  **.** {H13741} T
27810 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
27820 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
27830 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
27840 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
27850 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
27860 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
27870 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
27880 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
27890 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20  which the.**    
278a0 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74        Nth result
278b0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b   column of the [
278c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
278d0 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74  nt] S is extract
278e0 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed,.**          
278f0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
27900 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
27910 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
27920 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ession.**       
27930 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20     or if unable 
27940 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
27950 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ry to store the 
27960 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  name..**.** {H13
27970 37 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  742} The [sqlite
27980 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
27990 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  e_name16(S,N)] i
279a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
279b0 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
279c0 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
279d0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
279e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
279f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
27a00 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20  abase.**        
27a10 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65    from which the
27a20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
27a30 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  mn of the [prepa
27a40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
27a50 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
27a60 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
27a70 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
27a80 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67  lumn of S is a g
27a90 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
27aa0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
27ab0 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
27ac0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
27ad0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
27ae0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 33 7d 20  .**.** {H13743} 
27af0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
27b00 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53  umn_table_name(S
27b10 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
27b20 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
27b30 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
27b40 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
27b50 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
27b60 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68  table from which
27b70 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27b80 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
27b90 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  mn of the [prepa
27ba0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
27bb0 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a   is extracted,.*
27bc0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55  *          or NU
27bd0 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
27be0 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67  lumn of S is a g
27bf0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
27c00 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
27c10 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
27c20 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
27c30 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
27c40 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 34 7d 20  .**.** {H13744} 
27c50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
27c60 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
27c70 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
27c80 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
27c90 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
27ca0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
27cb0 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65  te order zero-te
27cc0 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
27cd0 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20   the table.**   
27ce0 20 20 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63         from whic
27cf0 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  h the Nth result
27d00 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b   column of the [
27d10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27d20 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20  nt] S is.**     
27d30 20 20 20 20 20 65 78 74 72 61 63 74 65 64 2c 20       extracted, 
27d40 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
27d50 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
27d60 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
27d70 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ession.**       
27d80 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20     or if unable 
27d90 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
27da0 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ry to store the 
27db0 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  name..**.** {H13
27dc0 37 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  745} The [sqlite
27dd0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
27de0 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  name(S,N)] inter
27df0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
27e00 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
27e10 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  the UTF-8 zero-t
27e20 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
27e30 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
27e40 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  mn from which th
27e50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
27e60 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
27e70 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  of the [prepared
27e80 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
27e90 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20   extracted,.**  
27ea0 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20          or NULL 
27eb0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
27ec0 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65  n of S is a gene
27ed0 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  ral expression.*
27ee0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
27ef0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
27f00 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74  ate memory to st
27f10 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
27f20 0a 2a 2a 20 7b 48 31 33 37 34 36 7d 20 54 68 65  .** {H13746} The
27f30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
27f40 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53  _origin_name16(S
27f50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
27f60 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
27f70 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
27f80 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
27f90 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d   order zero-term
27fa0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
27fb0 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  he table.**     
27fc0 20 20 20 20 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d       column from
27fd0 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72   which the Nth r
27fe0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
27ff0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
28000 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28010 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63  ent] S is extrac
28020 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
28030 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a  the Nth column.*
28040 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 53 20  *          of S 
28050 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
28060 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e  ression or if un
28070 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
28080 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20   memory.**      
28090 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65      to store the
280a0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   name..**.** {H1
280b0 33 37 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e  3748} The return
280c0 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20   values from.** 
280d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
280e0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
280f0 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
28100 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
28110 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ces].**         
28120 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 74   are valid for t
28130 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74  he lifetime of t
28140 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
28150 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20  tement].**      
28160 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65      or until the
28170 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61   encoding is cha
28180 6e 67 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20  nged by another 
28190 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20  metadata.**     
281a0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63       interface c
281b0 61 6c 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65  all for the same
281c0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
281d0 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  ent and column..
281e0 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
281f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31  S:.**.** {A13751
28200 7d 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  } If two or more
28210 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
28220 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20  e or more.**    
28230 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
28240 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
28250 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
28260 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
28270 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  ].**          fo
28280 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
28290 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
282a0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
282b0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74  n.**          at
282c0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
282d0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
282e0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
282f0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
28300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
28310 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
28320 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
28330 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
28340 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
28350 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
28360 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
28370 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
28380 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
28390 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
283a0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
283b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
283c0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
283d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
283e0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
283f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
28400 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
28410 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
28420 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
28430 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
28440 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
28450 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
28460 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
28470 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
28480 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
28490 20 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30   {H13760} <S1070
284a0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  0>.**.** The fir
284b0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
284c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
284d0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
284e0 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
284f0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
28500 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
28510 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
28520 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
28530 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
28540 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
28550 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
28560 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
28570 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
28580 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
28590 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
285a0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
285b0 75 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e  urned.  If the N
285c0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
285d0 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
285e0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
285f0 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
28600 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
28610 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
28620 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74   The returned st
28630 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
28640 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45  TF-8 encoded. {E
28650 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ND}.**.** For ex
28660 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
28670 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
28680 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
28690 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
286a0 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
286b0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
286c0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
286d0 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
286e0 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
286f0 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
28700 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
28710 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
28720 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
28730 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
28740 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
28750 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
28760 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
28770 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
28780 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a  umn (i==0)..**.*
28790 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  * SQLite uses dy
287a0 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
287b0 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20  yping.  So just 
287c0 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
287d0 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
287e0 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
287f0 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
28800 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
28810 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
28820 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
28830 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
28840 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
28850 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
28860 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
28870 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
28880 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
28890 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
288a0 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
288b0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
288c0 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
288d0 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
288e0 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
288f0 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  es..**.** INVARI
28900 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
28910 37 36 31 7d 20 20 41 20 73 75 63 63 65 73 73 66  761}  A successf
28920 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
28930 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
28940 79 70 65 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e  ype(S,N)] return
28950 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
28960 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
28970 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f   UTF-8 string co
28980 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63  ntaining the dec
28990 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 0a 2a  lared datatype.*
289a0 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  *           of t
289b0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
289c0 74 68 61 74 20 61 70 70 65 61 72 73 20 61 73 20  that appears as 
289d0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
289e0 6e 75 6d 62 65 72 65 64 0a 2a 2a 20 20 20 20 20  numbered.**     
289f0 20 20 20 20 20 20 66 72 6f 6d 20 30 29 20 6f 66        from 0) of
28a00 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
28a10 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
28a20 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
28a30 2a 0a 2a 2a 20 7b 48 31 33 37 36 32 7d 20 20 41  *.** {H13762}  A
28a40 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
28a50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
28a60 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53  umn_decltype16(S
28a70 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
28a80 20 20 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f    returns a zero
28a90 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
28aa0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
28ab0 72 64 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20  rder string.**  
28ac0 20 20 20 20 20 20 20 20 20 63 6f 6e 74 61 69 6e           contain
28ad0 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64  ing the declared
28ae0 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65   datatype of the
28af0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
28b00 61 74 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20  at appears.**   
28b10 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20 4e          as the N
28b20 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65  th column (numbe
28b30 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74  red from 0) of t
28b40 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f  he result set to
28b50 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
28b60 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
28b70 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20  ement] S..**.** 
28b80 7b 48 31 33 37 36 33 7d 20 20 49 66 20 4e 20 69  {H13763}  If N i
28b90 73 20 6c 65 73 73 20 74 68 61 6e 20 30 20 6f 72  s less than 0 or
28ba0 20 4e 20 69 73 20 67 72 65 61 74 65 72 20 74 68   N is greater th
28bb0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a  an or equal to.*
28bc0 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20  *           the 
28bd0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
28be0 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  s in the [prepar
28bf0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c  ed statement] S,
28c00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72  .**           or
28c10 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
28c20 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78  mn of S is an ex
28c30 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
28c40 75 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20  uery rather.**  
28c50 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 61 20           than a 
28c60 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72  table column, or
28c70 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
28c80 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a  ocation failure.
28c90 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63  **           occ
28ca0 75 72 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64  urs during encod
28cb0 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c  ing conversions,
28cc0 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
28cd0 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c     calls to [sql
28ce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
28cf0 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  type(S,N)] or.**
28d00 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
28d10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
28d20 79 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75  ype16(S,N)] retu
28d30 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73  rn NULL..*/.cons
28d40 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28d50 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
28d60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
28d70 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
28d80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
28d90 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65  ecltype16(sqlite
28da0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
28db0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
28dc0 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
28dd0 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30  tatement {H13200
28de0 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10000>.**.**
28df0 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
28e00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
28e10 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
28e20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
28e30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28e40 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
28e50 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
28e60 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
28e70 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
28e80 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
28e90 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
28ea0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
28eb0 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
28ec0 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
28ed0 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
28ee0 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
28ef0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
28f00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
28f10 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
28f20 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
28f30 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
28f40 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
28f50 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
28f60 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
28f70 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
28f80 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
28f90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
28fa0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
28fb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28fc0 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
28fd0 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
28fe0 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
28ff0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
29000 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
29010 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
29020 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
29030 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
29040 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
29050 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
29060 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
29070 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
29080 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
29090 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
290a0 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63  .** In the legac
290b0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
290c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
290d0 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
290e0 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
290f0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
29100 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
29110 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
29120 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
29130 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22  ** With the "v2"
29140 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20   interface, any 
29150 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65  of the other [re
29160 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a  sult codes] or.*
29170 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
29180 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20  lt codes] might 
29190 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77  be returned as w
291a0 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  ell..**.** [SQLI
291b0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
291c0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
291d0 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
291e0 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
291f0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
29200 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
29210 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20  do its job.  If 
29220 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
29230 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
29240 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
29250 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
29260 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
29270 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
29280 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
29290 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
292a0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
292b0 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
292c0 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70   within a.** exp
292d0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
292e0 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
292f0 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
29300 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
29310 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
29320 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  .**.** [SQLITE_D
29330 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
29340 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
29350 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
29360 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
29370 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
29380 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
29390 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
293a0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
293b0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
293c0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
293d0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
293e0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
293f0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
29400 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
29410 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
29420 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
29430 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
29440 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
29450 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
29460 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
29470 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
29480 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
29490 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
294a0 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
294b0 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
294c0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
294d0 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
294e0 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
294f0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
29500 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
29510 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
29520 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
29530 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
29540 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  data..**.** [SQL
29550 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
29560 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
29570 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
29580 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
29590 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
295a0 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
295b0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
295c0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
295d0 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
295e0 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
295f0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
29600 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
29610 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
29620 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63  * With the legac
29630 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
29640 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
29650 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
29660 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
29670 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
29680 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
29690 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
296a0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
296b0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
296c0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
296d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
296e0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
296f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49  d statement].  I
29700 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
29710 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
29720 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
29730 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
29740 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
29750 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
29760 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
29770 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
29780 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
29790 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
297a0 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
297b0 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
297c0 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
297d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
297e0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
297f0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
29800 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
29810 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
29820 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
29830 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
29840 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
29850 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
29860 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
29870 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
29880 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
29890 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
298a0 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
298b0 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
298c0 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
298d0 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
298e0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  me..**.** <b>Goo
298f0 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
29900 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
29910 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
29920 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
29930 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
29940 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
29950 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
29960 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
29970 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
29980 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
29990 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
299a0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
299b0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
299c0 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
299d0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
299e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
299f0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
29a00 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
29a10 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
29a20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
29a30 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
29a40 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
29a50 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
29a60 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
29a70 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
29a80 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
29a90 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
29aa0 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
29ab0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
29ac0 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
29ad0 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
29ae0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
29af0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
29b00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29b10 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
29b20 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
29b30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29b40 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
29b50 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
29b60 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
29b70 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
29b80 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
29b90 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
29ba0 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
29bb0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
29bc0 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
29bd0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
29be0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
29bf0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
29c00 2a 0a 2a 2a 20 7b 48 31 33 32 30 32 7d 20 20 49  *.** {H13202}  I
29c10 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
29c20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20  statement] S is 
29c30 72 65 61 64 79 20 74 6f 20 62 65 20 72 75 6e 2c  ready to be run,
29c40 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
29c50 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70     [sqlite3_step
29c60 28 53 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68  (S)] advances th
29c70 61 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  at prepared stat
29c80 65 6d 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20 20  ement until.**  
29c90 20 20 20 20 20 20 20 20 20 63 6f 6d 70 6c 65 74           complet
29ca0 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20  ion or until it 
29cb0 69 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  is ready to retu
29cc0 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f  rn another row o
29cd0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
29ce0 20 20 20 72 65 73 75 6c 74 20 73 65 74 2c 20 6f     result set, o
29cf0 72 20 75 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69  r until an [sqli
29d00 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20  te3_interrupt | 
29d10 69 6e 74 65 72 72 75 70 74 5d 0a 2a 2a 20 20 20  interrupt].**   
29d20 20 20 20 20 20 20 20 20 6f 72 20 61 20 72 75 6e          or a run
29d30 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f 63 63 75  -time error occu
29d40 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30  rs..**.** {H1530
29d50 34 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20  4}  When a call 
29d60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
29d70 28 53 29 5d 20 63 61 75 73 65 73 20 74 68 65 20  (S)] causes the 
29d80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29d90 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ent].**         
29da0 20 20 53 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f    S to run to co
29db0 6d 70 6c 65 74 69 6f 6e 2c 20 74 68 65 20 66 75  mpletion, the fu
29dc0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b  nction returns [
29dd0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a  SQLITE_DONE]..**
29de0 0a 2a 2a 20 7b 48 31 35 33 30 36 7d 20 20 57 68  .** {H15306}  Wh
29df0 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  en a call to [sq
29e00 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73  lite3_step(S)] s
29e10 74 6f 70 73 20 62 65 63 61 75 73 65 20 69 74 20  tops because it 
29e20 69 73 20 72 65 61 64 79 20 74 6f 0a 2a 2a 20 20  is ready to.**  
29e30 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
29e40 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74  another row of t
29e50 68 65 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69  he result set, i
29e60 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  t returns [SQLIT
29e70 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  E_ROW]..**.** {H
29e80 31 35 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c  15308}  If a cal
29e90 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
29ea0 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72  ep(S)] encounter
29eb0 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  s an.**         
29ec0 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72    [sqlite3_inter
29ed0 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74  rupt | interrupt
29ee0 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20  ] or a run-time 
29ef0 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20  error,.**       
29f00 20 20 20 20 69 74 20 72 65 74 75 72 6e 73 20 61      it returns a
29f10 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
29f20 72 6f 72 20 63 6f 64 65 20 74 68 61 74 20 69 73  ror code that is
29f30 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20   not one of.**  
29f40 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
29f50 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  _OK], [SQLITE_RO
29f60 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  W], or [SQLITE_D
29f70 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ONE]..**.** {H15
29f80 33 31 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c  310}  If an [sql
29f90 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
29fa0 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61   interrupt] or a
29fb0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a   run-time error.
29fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63 63  **           occ
29fd0 75 72 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c  urs during a cal
29fe0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
29ff0 65 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ep(S)].**       
2a000 20 20 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61      for a [prepa
2a010 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2a020 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
2a030 2a 20 20 20 20 20 20 20 20 20 20 20 6c 65 67 61  *           lega
2a040 63 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  cy interfaces [s
2a050 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2a060 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
2a070 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
2a080 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68  re16()], then th
2a090 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  e function retur
2a0a0 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
2a0b0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45         [SQLITE_E
2a0c0 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  RROR], [SQLITE_B
2a0d0 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  USY], or [SQLITE
2a0e0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74  _MISUSE]..*/.int
2a0f0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
2a100 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2a110 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2a120 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2a130 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
2a140 20 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30   {H13770} <S1070
2a150 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73  0>.**.** Returns
2a160 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76   the number of v
2a170 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75 72  alues in the cur
2a180 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2a190 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a  result set..**.*
2a1a0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2a1b0 0a 2a 2a 20 7b 48 31 33 37 37 31 7d 20 20 41 66  .** {H13771}  Af
2a1c0 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ter a call to [s
2a1d0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2a1e0 74 68 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51  that returns [SQ
2a1f0 4c 49 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20  LITE_ROW],.**   
2a200 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
2a210 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2a220 53 29 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  S)] routine will
2a230 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
2a240 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20   value.**       
2a250 20 20 20 20 61 73 20 74 68 65 20 5b 73 71 6c 69      as the [sqli
2a260 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2a270 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  (S)] function..*
2a280 2a 0a 2a 2a 20 7b 48 31 33 37 37 32 7d 20 20 41  *.** {H13772}  A
2a290 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
2a2a0 65 70 28 53 29 5d 20 68 61 73 20 72 65 74 75 72  ep(S)] has retur
2a2b0 6e 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  ned any value ot
2a2c0 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
2a2d0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f        [SQLITE_RO
2a2e0 57 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71  W] or before [sq
2a2f0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
2a300 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  as been called o
2a310 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
2a320 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2a330 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20  tement] for the 
2a340 66 69 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65  first time since
2a350 20 69 74 20 77 61 73 0a 2a 2a 20 20 20 20 20 20   it was.**      
2a360 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
2a370 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
2a380 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2a390 73 65 74 20 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a  set | reset],.**
2a3a0 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b             the [
2a3b0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2a3c0 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 72  nt(S)] routine r
2a3d0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a  eturns zero..*/.
2a3e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
2a3f0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2a400 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2a410 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2a420 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
2a430 70 65 73 20 7b 48 31 30 32 36 35 7d 20 3c 53 31  pes {H10265} <S1
2a440 30 31 31 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a  0110><S10120>.**
2a450 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
2a460 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31  E_TEXT.**.** {H1
2a470 30 32 36 36 7d 20 45 76 65 72 79 20 76 61 6c 75  0266} Every valu
2a480 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
2a490 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
2a4a0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
2a4b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2a4c0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
2a4d0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
2a4e0 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
2a4f0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2a500 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
2a510 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
2a520 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
2a530 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a  * </ul> {END}.**
2a540 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2a550 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
2a560 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
2a570 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
2a580 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
2a590 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
2a5a0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
2a5b0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2a5c0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
2a5d0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
2a5e0 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
2a5f0 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
2a600 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
2a610 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
2a620 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
2a630 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
2a640 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
2a650 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
2a660 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2a670 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
2a680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
2a690 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
2a6a0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
2a6b0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
2a6c0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
2a6d0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2a6e0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
2a6f0 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
2a700 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
2a710 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
2a720 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
2a730 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
2a740 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
2a750 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
2a760 79 20 7b 48 31 33 38 30 30 7d 20 3c 53 31 30 37  y {H13800} <S107
2a770 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2a780 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
2a790 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
2a7a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2a7b0 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
2a7c0 20 73 65 74 20 71 75 65 72 79 22 20 69 6e 74 65   set query" inte
2a7d0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
2a7e0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2a7f0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2a800 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
2a810 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
2a820 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
2a830 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49  w of a query.  I
2a840 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
2a850 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2a860 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
2a870 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
2a880 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2a890 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
2a8a0 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
2a8b0 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
2a8c0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
2a8d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
2a8e0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
2a8f0 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
2a900 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
2a910 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2a920 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2a930 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
2a940 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
2a950 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
2a960 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f  ned.  The leftmo
2a970 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
2a980 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
2a990 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a  the index 0..**.
2a9a0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
2a9b0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2a9c0 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
2a9d0 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
2a9e0 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
2a9f0 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
2aa00 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
2aa10 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2aa20 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
2aa30 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
2aa40 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
2aa50 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2aa60 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2aa70 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2aa80 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2aa90 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
2aaa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2aab0 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
2aac0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
2aad0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
2aae0 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
2aaf0 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
2ab00 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2ab10 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
2ab20 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2ab30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2ab40 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
2ab50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ab60 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
2ab70 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
2ab80 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2ab90 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
2aba0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2abb0 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
2abc0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2abd0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2abe0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2abf0 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
2ac00 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
2ac10 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
2ac20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2ac30 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
2ac40 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
2ac50 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2ac60 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ined..**.** The 
2ac70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ac80 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
2ac90 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
2aca0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2acb0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
2acc0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
2acd0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
2ace0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
2acf0 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 76    The returned v
2ad00 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
2ad10 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2ad20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
2ad30 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2ad40 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
2ad50 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
2ad60 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
2ad70 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
2ad80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2ad90 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
2ada0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
2adb0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
2adc0 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
2add0 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
2ade0 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
2adf0 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
2ae00 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
2ae10 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2ae20 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
2ae30 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
2ae40 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
2ae50 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
2ae60 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
2ae70 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
2ae80 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
2ae90 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
2aea0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  version..**.** I
2aeb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2aec0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
2aed0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2aee0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2aef0 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
2af00 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2af10 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2af20 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2af30 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ring..** If the 
2af40 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
2af50 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
2af60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2af70 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
2af80 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2af90 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
2afa0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2afb0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2afc0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2afd0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2afe0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2aff0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2b000 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2b010 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2b020 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2b030 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2b040 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2b050 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2b060 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2b070 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ing..** The valu
2b080 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  e returned does 
2b090 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
2b0a0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2b0b0 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
2b0c0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f   the string.  Fo
2b0d0 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
2b0e0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
2b0f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
2b100 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
2b110 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
2b120 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2b130 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e  ers..**.** Strin
2b140 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
2b150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b160 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
2b170 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2b180 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
2b190 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
2b1a0 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  ays zero termina
2b1b0 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e  ted.  The return
2b1c0 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
2b1d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2b1e0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
2b1f0 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
2b200 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70  n arbitrary.** p
2b210 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79  ointer, possibly
2b220 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   even a NULL poi
2b230 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
2b240 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2b250 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65  ytes16() routine
2b260 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73   is similar to s
2b270 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2b280 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61  tes().** but lea
2b290 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69  ves the result i
2b2a0 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  n UTF-16 in nati
2b2b0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e  ve byte order in
2b2c0 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a  stead of UTF-8..
2b2d0 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** The zero term
2b2e0 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e  inator is not in
2b2f0 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63  cluded in this c
2b300 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ount..**.** The 
2b310 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2b320 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
2b330 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
2b340 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
2b350 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2b360 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70   object.  An unp
2b370 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2b380 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a  _value object.**
2b390 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2b3a0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
2b3b0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
2b3c0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
2b3d0 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
2b3e0 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
2b3f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b400 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
2b410 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2b420 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2b430 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
2b440 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
2b450 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
2b460 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
2b470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2b480 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
2b490 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2b4a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2b4b0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
2b4c0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2b4d0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2b4e0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2b4f0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
2b500 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
2b510 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
2b520 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
2b530 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
2b540 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
2b550 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
2b560 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
2b570 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
2b580 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2b590 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
2b5a0 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
2b5b0 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
2b5c0 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
2b5d0 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  .  The following
2b5e0 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
2b5f0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
2b600 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
2b610 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
2b620 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2b630 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2b640 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
2b650 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
2b660 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
2b670 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
2b680 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2b690 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
2b6a0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
2b6b0 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
2b6c0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2b6d0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2b6e0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
2b6f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2b700 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
2b710 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2b720 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
2b730 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2b740 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
2b750 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
2b760 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
2b770 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2b780 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2b790 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2b7a0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2b7b0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2b7c0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2b7d0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2b7e0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2b7f0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2b800 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2b810 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2b820 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2b830 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2b840 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2b850 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2b860 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2b870 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
2b880 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2b890 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2b8a0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2b8b0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2b8c0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
2b8d0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2b8e0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2b8f0 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
2b900 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
2b910 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2b920 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2b930 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
2b940 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2b950 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2b960 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
2b970 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2b980 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
2b990 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
2b9a0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
2b9b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
2b9c0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
2b9d0 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
2b9e0 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
2b9f0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2ba00 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2ba10 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
2ba20 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
2ba30 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
2ba40 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2ba50 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2ba60 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
2ba70 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
2ba80 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
2ba90 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
2baa0 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
2bab0 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
2bac0 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
2bad0 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
2bae0 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
2baf0 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
2bb00 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
2bb10 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
2bb20 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
2bb30 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
2bb40 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
2bb50 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
2bb60 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
2bb70 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
2bb80 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
2bb90 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
2bba0 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
2bbb0 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
2bbc0 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
2bbd0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2bbe0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
2bbf0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
2bc00 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
2bc10 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
2bc20 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2bc30 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
2bc40 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2bc50 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
2bc60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2bc70 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
2bc80 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
2bc90 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
2bca0 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
2bcb0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
2bcc0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
2bcd0 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
2bce0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2bcf0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2bd00 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
2bd10 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2bd20 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
2bd30 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2bd40 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
2bd50 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
2bd60 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
2bd70 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
2bd80 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
2bd90 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
2bda0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2bdb0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
2bdc0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2bdd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2bde0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2bdf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2be00 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2be10 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2be20 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2be30 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
2be40 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
2be50 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2be60 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
2be70 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2be80 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2be90 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2bea0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
2beb0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2bec0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2bed0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2bee0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
2bef0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43  ** </ul>.**.** C
2bf00 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
2bf10 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
2bf20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
2bf30 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
2bf40 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
2bf50 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
2bf60 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
2bf70 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
2bf80 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2bf90 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
2bfa0 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
2bfb0 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20   points to will 
2bfc0 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
2bfd0 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
2bfe0 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
2bff0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
2c000 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
2c010 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
2c020 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
2c030 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
2c040 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
2c050 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
2c060 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
2c070 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
2c080 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
2c090 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
2c0a0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
2c0b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2c0c0 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
2c0d0 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
2c0e0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
2c0f0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2c100 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
2c110 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2c120 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2c130 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2c140 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2c150 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2c160 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2c170 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2c180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c190 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
2c1a0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2c1b0 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
2c1c0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2c1d0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2c1e0 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
2c1f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c200 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
2c210 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2c220 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2c230 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
2c240 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
2c250 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
2c260 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
2c270 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
2c280 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c290 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
2c2a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2c2b0 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
2c2c0 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
2c2d0 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
2c2e0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
2c2f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2c300 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2c310 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
2c320 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2c330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c340 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
2c350 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
2c360 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c370 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
2c380 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2c390 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
2c3a0 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
2c3b0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
2c3c0 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
2c3d0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
2c3e0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
2c3f0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
2c400 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
2c410 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2c420 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2c430 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2c440 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
2c450 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63   The memory spac
2c460 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
2c470 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
2c480 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
2c490 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
2c4a0 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
2c4b0 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
2c4c0 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
2c4d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
2c4e0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
2c4f0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
2c500 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
2c510 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
2c520 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
2c530 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
2c540 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
2c550 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
2c560 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
2c570 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
2c580 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
2c590 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
2c5a0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
2c5b0 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
2c5c0 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
2c5d0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
2c5e0 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
2c5f0 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
2c600 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
2c610 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
2c620 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
2c630 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
2c640 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2c650 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 33 7d  :.**.** {H13803}
2c660 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2c670 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20  lumn_blob(S,N)] 
2c680 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2c690 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2c6a0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
2c6b0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
2c6c0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2c6d0 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
2c6e0 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
2c6f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2c700 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68  to a BLOB and th
2c710 65 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20  en returns a.** 
2c720 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
2c730 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65   to the converte
2c740 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b  d value..**.** {
2c750 48 31 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c  H13806} The [sql
2c760 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c770 73 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  s(S,N)] interfac
2c780 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2c790 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2c7a0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2c7b0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
2c7c0 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2c7d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2c7e0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2c7f0 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2c800 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2c810 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2c820 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2c830 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2c840 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d  olumn_blob(S,N)]
2c850 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2c860 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c870 74 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a  text(S,N)]..**.*
2c880 2a 20 7b 48 31 33 38 30 39 7d 20 54 68 65 20 5b  * {H13809} The [
2c890 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c8a0 79 74 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74  ytes16(S,N)] int
2c8b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2c8c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
2c8d0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2c8e0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78  n the string (ex
2c8f0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
2c900 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
2c910 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
2c920 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
2c930 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
2c940 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
2c950 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2c960 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
2c970 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e  mn_text16(S,N)].
2c980 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 32 7d 20  .**.** {H13812} 
2c990 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
2c9a0 75 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d  umn_double(S,N)]
2c9b0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2c9c0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2c9d0 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
2c9e0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
2c9f0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2ca00 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  set for the.**  
2ca10 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2ca20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2ca30 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  nto a floating p
2ca40 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a  oint value and.*
2ca50 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2ca60 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61  ns a copy of tha
2ca70 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b  t value..**.** {
2ca80 48 31 33 38 31 35 7d 20 54 68 65 20 5b 73 71 6c  H13815} The [sql
2ca90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
2caa0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2cab0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2cac0 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
2cad0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2cae0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2caf0 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65  sult set for the
2cb00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2cb10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cb20 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  ] S into a 64-bi
2cb30 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2cb40 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2cb50 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77   returns the low
2cb60 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68  er 32 bits of th
2cb70 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
2cb80 2a 20 7b 48 31 33 38 31 38 7d 20 54 68 65 20 5b  * {H13818} The [
2cb90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2cba0 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72  nt64(S,N)] inter
2cbb0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2cbc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
2cbd0 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2cbe0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2cbf0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
2cc00 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2cc10 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2cc20 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
2cc30 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2cc40 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
2cc50 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
2cc60 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74  copy of that int
2cc70 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  eger..**.** {H13
2cc80 38 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  821} The [sqlite
2cc90 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c  3_column_text(S,
2cca0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
2ccb0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2ccc0 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2ccd0 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2cce0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2ccf0 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
2cd00 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70         the [prep
2cd10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cd20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  S into a zero-te
2cd30 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
2cd40 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
2cd50 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
2cd60 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2cd70 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
2cd80 31 33 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  13824} The [sqli
2cd90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2cda0 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
2cdb0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2cdc0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
2cdd0 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
2cde0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2cdf0 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74  result set for t
2ce00 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2ce10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ce20 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72  nt] S into a zer
2ce30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62  o-terminated 2-b
2ce40 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  yte.**          
2ce50 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e  aligned UTF-16 n
2ce60 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2ce70 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2ce80 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
2ce90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
2cea0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
2ceb0 7b 48 31 33 38 32 37 7d 20 54 68 65 20 5b 73 71  {H13827} The [sq
2cec0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2ced0 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
2cee0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
2cef0 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51        one of [SQ
2cf00 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_NULL], [SQL
2cf10 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53  ITE_INTEGER], [S
2cf20 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a  QLITE_FLOAT],.**
2cf30 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2cf40 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c  E_TEXT], or [SQL
2cf50 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70  ITE_BLOB] as app
2cf60 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20  ropriate for.** 
2cf70 20 20 20 20 20 20 20 20 20 74 68 65 20 4e 74 68           the Nth
2cf80 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
2cf90 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2cfa0 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
2cfb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2cfc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cfd0 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
2cfe0 48 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c  H13830} The [sql
2cff0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2d000 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
2d010 65 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20  e returns a.**  
2d020 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20          pointer 
2d030 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  to an [unprotect
2d040 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d050 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65  ] object for the
2d060 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
2d070 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
2d080 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2d090 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
2d0a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2d0b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d0c0 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73  ment] S..*/.cons
2d0d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2d0e0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
2d0f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2d100 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2d110 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
2d120 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d130 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2d140 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d150 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
2d160 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
2d170 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
2d180 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
2d190 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2d1a0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2d1b0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
2d1c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2d1d0 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
2d1e0 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
2d1f0 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
2d200 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2d210 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
2d220 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
2d230 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
2d240 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2d250 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
2d260 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2d270 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2d280 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d290 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2d2a0 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
2d2b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d2c0 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
2d2d0 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
2d2e0 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
2d2f0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d300 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d310 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
2d320 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2d330 4f 62 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20  Object {H13300} 
2d340 3c 53 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e  <S70300><S30100>
2d350 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2d360 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
2d370 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
2d380 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
2d390 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d3a0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61  ]..** If the sta
2d3b0 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75  tement was execu
2d3c0 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ted successfully
2d3d0 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64   or not executed
2d3e0 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a   at all, then.**
2d3f0 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65   SQLITE_OK is re
2d400 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75  turned. If execu
2d410 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
2d420 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65  ement failed the
2d430 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  n an.** [error c
2d440 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
2d450 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
2d460 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2d470 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61   This routine ca
2d480 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
2d490 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20  ny point during 
2d4a0 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
2d4b0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2d4c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49  d statement].  I
2d4d0 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61  f the virtual ma
2d4e0 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a  chine has not.**
2d4f0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
2d500 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72  tion when this r
2d510 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
2d520 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a  , that is like.*
2d530 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61  * encountering a
2d540 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73  n error or an [s
2d550 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
2d560 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a   | interrupt]..*
2d570 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64  * Incomplete upd
2d580 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c  ates may be roll
2d590 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e  ed back and tran
2d5a0 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65  sactions cancele
2d5b0 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20  d,.** depending 
2d5c0 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61  on the circumsta
2d5d0 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a  nces, and the.**
2d5e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65   [error code] re
2d5f0 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b  turned will be [
2d600 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a  SQLITE_ABORT]..*
2d610 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2d620 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 32 7d 20  .**.** {H11302} 
2d630 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  The [sqlite3_fin
2d640 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74 65 72 66  alize(S)] interf
2d650 61 63 65 20 64 65 73 74 72 6f 79 73 20 74 68 65  ace destroys the
2d660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2d670 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d680 5d 20 53 20 61 6e 64 20 72 65 6c 65 61 73 65 73  ] S and releases
2d690 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
2d6a0 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65   memory and file
2d6b0 20 72 65 73 6f 75 72 63 65 73 20 68 65 6c 64 20   resources held 
2d6c0 62 79 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a  by that object..
2d6d0 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 34 7d 20 49  **.** {H11304} I
2d6e0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2d6f0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2d700 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2d710 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d720 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d730 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
2d740 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20  an error,.**    
2d750 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69        then [sqli
2d760 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d  te3_finalize(S)]
2d770 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 73 61   returns that sa
2d780 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74  me error..*/.int
2d790 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2d7a0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
2d7b0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2d7c0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2d7d0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2d7e0 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33  ent Object {H133
2d7f0 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  30} <S70300>.**.
2d800 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2d810 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
2d820 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
2d830 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
2d840 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2d850 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
2d860 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
2d870 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
2d880 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53  ecuted..** Any S
2d890 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
2d8a0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
2d8b0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
2d8c0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
2d8d0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2d8e0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
2d8f0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
2d900 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
2d910 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
2d920 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2d930 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2d940 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
2d950 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73   {H11332} The [s
2d960 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2d970 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
2d980 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
2d990 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
2d9a0 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f           back to
2d9b0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
2d9c0 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
2d9d0 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66  *.** {H11334} If
2d9e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2d9f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2da00 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2da10 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2da20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2da30 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
2da40 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
2da50 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
2da60 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
2da70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2da80 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
2da90 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
2daa0 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  n S,.**         
2dab0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
2dac0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2dad0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
2dae0 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20  .** {H11336} If 
2daf0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2db00 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2db10 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
2db20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2db30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2db40 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
2db50 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
2db60 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2db70 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2db80 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
2db90 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2dba0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d  ..**.** {H11338}
2dbb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
2dbc0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
2dbd0 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
2dbe0 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
2dbf0 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20           of any 
2dc00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2dc10 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
2dc20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2dc30 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
2dc40 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
2dc50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2dc60 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2dc70 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
2dc80 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
2dc90 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30  unctions {H16100
2dca0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45  } <S20200>.** KE
2dcb0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
2dcc0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2dcd0 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
2dce0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2dcf0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2dd00 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
2dd10 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2dd20 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2dd30 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
2dd40 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  e two functions 
2dd50 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
2dd60 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
2dd70 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2dd80 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
2dd90 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
2dda0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2ddb0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
2ddc0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
2ddd0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
2dde0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2ddf0 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
2de00 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
2de10 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20   between the.** 
2de20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20  two is that the 
2de30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2de40 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  , the name of th
2de50 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74  e (scalar) funct
2de60 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2de70 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20  ate, is encoded 
2de80 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c  in UTF-8 for sql
2de90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2dea0 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31  tion() and UTF-1
2deb0 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  6.** for sqlite3
2dec0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ded0 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
2dee0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2def0 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
2df00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
2df10 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
2df20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
2df30 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61 20  be added.  If a 
2df40 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75  single program u
2df50 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
2df60 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2df70 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61  nnection interna
2df80 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75  lly, then SQL fu
2df90 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
2dfa0 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c  added individual
2dfb0 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61  ly to.** each da
2dfc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2dfd0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  n..**.** The sec
2dfe0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2dff0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2e000 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
2e010 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
2e020 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68  * redefined.  Th
2e030 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
2e040 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
2e050 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78  to 255 bytes, ex
2e060 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68  clusive of.** th
2e070 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
2e080 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  r.  Note that th
2e090 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69  e name length li
2e0a0 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c  mit is in bytes,
2e0b0 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65   not.** characte
2e0c0 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74  rs.  Any attempt
2e0d0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
2e0e0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
2e0f0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
2e100 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
2e110 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20  TE_ERROR] being 
2e120 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2e130 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
2e140 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
2e150 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
2e160 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
2e170 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2e180 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
2e190 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61  akes. If this pa
2e1a0 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
2e1b0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51  ive, then the SQ
2e1c0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2e1d0 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
2e1e0 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
2e1f0 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  f arguments..**.
2e200 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
2e210 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
2e220 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
2e230 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
2e240 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
2e250 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
2e260 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
2e270 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
2e280 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e  rs.  Any SQL fun
2e290 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2e2a0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61  tion should be a
2e2b0 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
2e2c0 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20  ork with UTF-8, 
2e2d0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
2e2e0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
2e2f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2e300 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
2e310 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
2e320 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
2e330 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73   another.  It is
2e340 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69   allowed to.** i
2e350 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
2e360 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2e370 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2e380 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
2e390 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
2e3a0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
2e3b0 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
2e3c0 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
2e3d0 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
2e3e0 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  * When multiple 
2e3f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2e400 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2e410 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
2e420 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
2e430 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
2e440 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
2e450 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
2e460 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
2e470 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
2e480 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
2e490 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2e4a0 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
2e4b0 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
2e4c0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
2e4d0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
2e4e0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
2e4f0 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
2e500 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66  ]..**.** The fif
2e510 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2e520 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
2e530 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
2e540 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2e550 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
2e560 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
2e570 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
2e580 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
2e590 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _data()]..**.** 
2e5a0 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67  The seventh, eig
2e5b0 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61  hth and ninth pa
2e5c0 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
2e5d0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2e5e0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
2e5f0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
2e600 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
2e610 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2e620 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2e630 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63   aggregate. A sc
2e640 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2e650 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2e660 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2e670 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
2e680 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c  lback only, NULL
2e690 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64   pointers should
2e6a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
2e6b0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
2e6c0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
2e6d0 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53  . An aggregate S
2e6e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2e6f0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2e700 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
2e710 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
2e720 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65  d NULL should be
2e730 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
2e740 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  c. To delete an 
2e750 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
2e760 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
2e770 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
2e780 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
2e790 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
2e7a0 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70  s..**.** It is p
2e7b0 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
2e7c0 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
2e7d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2e7e0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
2e7f0 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
2e800 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
2e810 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
2e820 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
2e830 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
2e840 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
2e850 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2e860 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  s.  SQLite will 
2e870 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
2e880 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63  mentation most c
2e890 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
2e8a0 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
2e8b0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
2e8c0 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 41 20  ion is used.  A 
2e8d0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2e8e0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
2e8f0 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
2e900 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
2e910 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
2e920 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
2e930 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2e940 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
2e950 65 20 6e 41 72 67 2e 20 20 41 20 66 75 6e 63 74  e nArg.  A funct
2e960 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72  ion where the pr
2e970 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2e980 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73  oding.** matches
2e990 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2e9a0 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74  coding is a bett
2e9b0 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e  er.** match than
2e9c0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
2e9d0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  e the encoding i
2e9e0 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a  s different.  .*
2e9f0 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  * A function whe
2ea00 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2ea10 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
2ea20 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
2ea30 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
2ea40 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
2ea50 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2ea60 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2ea70 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
2ea80 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
2ea90 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
2eaa0 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69   Built-in functi
2eab0 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
2eac0 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
2ead0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2eae0 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54   functions..** T
2eaf0 68 65 20 66 69 72 73 74 20 61 70 70 6c 69 63 61  he first applica
2eb00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2eb10 63 74 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76  ction with a giv
2eb20 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65  en name override
2eb30 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69  s all.** built-i
2eb40 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74  n functions in t
2eb50 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
2eb60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69  e connection] wi
2eb70 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
2eb80 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
2eb90 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2eba0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66  ned functions of
2ebb0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f   the same name o
2ebc0 6e 6c 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a  nly override .**
2ebd0 20 70 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69   prior applicati
2ebe0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2ebf0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e  ions that are an
2ec00 20 65 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72   exact match for
2ec10 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2ec20 66 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  f parameters and
2ec30 20 70 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64   preferred encod
2ec40 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70  ing..**.** An ap
2ec50 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2ec60 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
2ec70 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
2ec80 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
2ec90 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
2eca0 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
2ecb0 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
2ecc0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
2ecd0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
2ece0 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
2ecf0 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
2ed00 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
2ed10 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
2ed20 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
2ed30 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2ed40 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 7d 20 54 68  *.** {H16103} Th
2ed50 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2ed60 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58  e_function16(D,X
2ed70 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
2ed80 20 73 68 61 6c 6c 20 62 65 68 61 76 65 0a 2a 2a   shall behave.**
2ed90 20 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71            as [sq
2eda0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2edb0 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20  ction(D,X,...)] 
2edc0 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 78 63  in every way exc
2edd0 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20  ept that it.**  
2ede0 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 72 65          interpre
2edf0 74 73 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  ts the X argumen
2ee00 74 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  t as zero-termin
2ee10 61 74 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20 20  ated UTF-16.**  
2ee20 20 20 20 20 20 20 20 20 6e 61 74 69 76 65 20 62          native b
2ee30 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61  yte order instea
2ee40 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65 72  d of as zero-ter
2ee50 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a  minated UTF-8..*
2ee60 2a 0a 2a 2a 20 7b 48 31 36 31 30 36 7d 20 41 20  *.** {H16106} A 
2ee70 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
2ee80 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
2ee90 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2eea0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2eeb0 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20  n(D,X,N,E,...)] 
2eec0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2eed0 72 65 67 69 73 74 65 72 0a 2a 2a 20 20 20 20 20  register.**     
2eee0 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73       or replaces
2eef0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2ef00 6f 6e 73 20 69 6e 20 74 68 65 20 5b 64 61 74 61  ons in the [data
2ef10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2ef20 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75   D.**          u
2ef30 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
2ef40 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2ef50 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e  n named X with N
2ef60 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20   parameters.**  
2ef70 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 76 69          and havi
2ef80 6e 67 20 61 20 70 72 65 66 65 72 72 65 64 20 74  ng a preferred t
2ef90 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  ext encoding of 
2efa0 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 39  E..**.** {H16109
2efb0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
2efc0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2efd0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2efe0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2eff0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ].**          sh
2f000 61 6c 6c 20 72 65 70 6c 61 63 65 20 74 68 65 20  all replace the 
2f010 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76  P, F, S, and L v
2f020 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79 20 70  alues from any p
2f030 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 0a  rior calls with.
2f040 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2f050 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e  same D, X, N, an
2f060 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a  d E values..**.*
2f070 2a 20 7b 48 31 36 31 31 32 7d 20 54 68 65 20 5b  * {H16112} The [
2f080 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f090 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29  unction(D,X,...)
2f0a0 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ] interface shal
2f0b0 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20  l fail.**       
2f0c0 20 20 20 69 66 20 74 68 65 20 53 51 4c 20 66 75     if the SQL fu
2f0d0 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73  nction name X is
2f0e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 6e  .**          lon
2f0f0 67 65 72 20 74 68 61 6e 20 32 35 35 20 62 79 74  ger than 255 byt
2f100 65 73 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  es exclusive of 
2f110 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
2f120 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  tor..**.** {H161
2f130 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  18} The [sqlite3
2f140 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2f150 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
2f160 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
2f170 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 66           shall f
2f180 61 69 6c 20 75 6e 6c 65 73 73 20 65 69 74 68 65  ail unless eithe
2f190 72 20 46 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20  r F is NULL and 
2f1a0 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d  S and L are non-
2f1b0 4e 55 4c 4c 20 6f 72 0a 2a 2a 2a 20 20 20 20 20  NULL or.***     
2f1c0 20 20 20 20 46 20 69 73 20 6e 6f 6e 2d 4e 55 4c      F is non-NUL
2f1d0 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72  L and S and L ar
2f1e0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e NULL..**.** {H
2f1f0 31 36 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  16121} The [sqli
2f200 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f210 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ion(D,...)] inte
2f220 72 66 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c  rface shall fail
2f230 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20  s with an.**    
2f240 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65        error code
2f250 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 53 59   of [SQLITE_BUSY
2f260 5d 20 69 66 20 74 68 65 72 65 20 65 78 69 73 74  ] if there exist
2f270 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f280 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20  ments].**       
2f290 20 20 20 61 73 73 6f 63 69 61 74 65 64 20 77 69     associated wi
2f2a0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
2f2b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
2f2c0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 34 7d 20 54  **.** {H16124} T
2f2d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2f2e0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2f2f0 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  N,...)] interfac
2f300 65 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74  e shall fail wit
2f310 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  h.**          an
2f320 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
2f330 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
2f340 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
2f350 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  less.**         
2f360 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
2f370 74 65 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a  ter than 127..**
2f380 0a 2a 2a 20 7b 48 31 36 31 32 37 7d 20 57 68 65  .** {H16127} Whe
2f390 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  n N is non-negat
2f3a0 69 76 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ive, the [sqlite
2f3b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f3c0 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a  n(D,X,N,...)].**
2f3d0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
2f3e0 61 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74  ace shall regist
2f3f0 65 72 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20  er callbacks to 
2f400 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  be invoked for t
2f410 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  he.**          S
2f420 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  QL function.**  
2f430 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20          named X 
2f440 77 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  when the number 
2f450 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  of arguments to 
2f460 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2f470 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2f480 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a  exactly N..**.**
2f490 20 7b 48 31 36 31 33 30 7d 20 57 68 65 6e 20 4e   {H16130} When N
2f4a0 20 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c   is -1, the [sql
2f4b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f4c0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
2f4d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
2f4e0 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67  erface shall reg
2f4f0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 73 20  ister callbacks 
2f500 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
2f510 72 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20  r the SQL.**    
2f520 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 6e        function n
2f530 61 6d 65 64 20 58 20 77 69 74 68 20 61 6e 79 20  amed X with any 
2f540 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2f550 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  nts..**.** {H161
2f560 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74  33} When calls t
2f570 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2f580 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2f590 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2f5a0 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69     specify multi
2f5b0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2f5c0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2f5d0 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20  function X.**   
2f5e0 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20         and when 
2f5f0 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  one implementati
2f600 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20  on has N>=0 and 
2f610 74 68 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d  the other has N=
2f620 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  (-1).**         
2f630 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2f640 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ion with a non-z
2f650 65 72 6f 20 4e 20 73 68 61 6c 6c 20 62 65 20 70  ero N shall be p
2f660 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  referred..**.** 
2f670 7b 48 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61  {H16136} When ca
2f680 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2f690 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2f6a0 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a  D,X,N,E,...)].**
2f6b0 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66            specif
2f6c0 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  y multiple imple
2f6d0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2f6e0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2f6f0 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  X with.**       
2f700 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62     the same numb
2f710 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2f720 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  N but with diffe
2f730 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  rent.**         
2f740 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68   encodings E, th
2f750 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  en the implement
2f760 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61  ation where E ma
2f770 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  tches the.**    
2f780 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 65        database e
2f790 6e 63 6f 64 69 6e 67 20 73 68 61 6c 6c 20 70 72  ncoding shall pr
2f7a0 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eferred..**.** {
2f7b0 48 31 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61  H16139} For an a
2f7c0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2f7d0 63 74 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73  ction created us
2f7e0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2f7f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f800 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2f810 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66  ,P,0,S,L)] the f
2f820 69 6e 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20  inalizer.**     
2f830 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20       function L 
2f840 73 68 61 6c 6c 20 61 6c 77 61 79 73 20 62 65 20  shall always be 
2f850 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20  invoked exactly 
2f860 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20  once if the.**  
2f870 20 20 20 20 20 20 20 20 73 74 65 70 20 66 75 6e          step fun
2f880 63 74 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65  ction S is calle
2f890 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
2f8a0 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  mes..**.** {H161
2f8b0 34 32 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20  42} When SQLite 
2f8c0 69 6e 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74  invokes either t
2f8d0 68 65 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65  he xFunc or xSte
2f8e0 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a  p function of.**
2f8f0 20 20 20 20 20 20 20 20 20 20 61 6e 20 61 70 70            an app
2f900 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f910 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2f920 20 61 67 67 72 65 67 61 74 65 20 63 72 65 61 74   aggregate creat
2f930 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ed.**          b
2f940 79 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  y [sqlite3_creat
2f950 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72  e_function()] or
2f960 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f970 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a  _function16()],.
2f980 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
2f990 20 74 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73   the array of [s
2f9a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2f9b0 6a 65 63 74 73 20 70 61 73 73 65 64 20 61 73 20  jects passed as 
2f9c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2f9d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2f9e0 73 68 61 6c 6c 20 62 65 20 5b 70 72 6f 74 65 63  shall be [protec
2f9f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2fa00 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69  e] objects..*/.i
2fa10 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2fa20 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
2fa30 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
2fa40 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
2fa50 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
2fa60 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
2fa70 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
2fa80 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
2fa90 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2faa0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2fab0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2fac0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
2fad0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2fae0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2faf0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
2fb00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2fb10 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2fb20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2fb30 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
2fb40 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
2fb50 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2fb60 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2fb70 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2fb80 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2fb90 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2fba0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2fbb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2fbc0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2fbd0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2fbe0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2fbf0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2fc00 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2fc10 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a  3_context*).);..
2fc20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fc30 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b  Text Encodings {
2fc40 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e  H10267} <S50200>
2fc50 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H16100>.**.** 
2fc60 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
2fc70 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
2fc80 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
2fc90 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
2fca0 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
2fcb0 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
2fcc0 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
2fcd0 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
2fce0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
2fcf0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
2fd00 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
2fd10 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
2fd20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
2fd30 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
2fd40 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
2fd50 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
2fd60 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
2fd70 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
2fd80 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71        5    /* sq
2fd90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2fda0 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64  ction only */.#d
2fdb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2fdc0 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
2fdd0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
2fde0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
2fdf0 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
2fe00 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
2fe10 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
2fe20 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
2fe30 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
2fe40 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
2fe50 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
2fe60 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
2fe70 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2fe80 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
2fe90 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
2fea0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
2feb0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
2fec0 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
2fed0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2fee0 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
2fef0 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
2ff00 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
2ff10 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
2ff20 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
2ff30 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
2ff40 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
2ff50 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
2ff60 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
2ff70 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
2ff80 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
2ff90 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  D.SQLITE_DEPRECA
2ffa0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2ffb0 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
2ffc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ffd0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2ffe0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2fff0 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
30000 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
30010 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
30020 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
30030 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
30040 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
30050 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
30060 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
30070 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
30080 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
30090 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
300a0 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
300b0 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
300c0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
300d0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
300e0 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
300f0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
30100 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69  3_int64,int),voi
30110 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
30120 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
30130 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
30140 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
30150 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
30160 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30  es {H15100} <S20
30170 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  200>.**.** The C
30180 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
30190 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
301a0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
301b0 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
301c0 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
301d0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
301e0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
301f0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
30200 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
30210 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
30220 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
30230 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
30240 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
30250 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
30260 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
30270 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
30280 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
30290 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
302a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
302b0 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
302c0 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
302d0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
302e0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
302f0 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20  tes..** The 4th 
30300 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
30310 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
30320 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
30330 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
30340 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30350 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
30360 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
30370 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30380 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
30390 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
303a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
303b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
303c0 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
303d0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
303e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
303f0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
30400 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
30410 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
30420 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
30430 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30440 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
30450 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
30460 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
30470 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
30480 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
30490 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
304a0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
304b0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ior..**.** These
304c0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
304d0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
304e0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
304f0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
30500 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
30510 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
30520 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
30530 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
30540 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30550 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
30560 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
30570 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
30580 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
30590 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
305a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
305b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
305c0 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
305d0 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
305e0 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
305f0 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
30600 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
30610 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71  hine.  The.** sq
30620 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30630 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
30640 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
30650 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
30660 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
30670 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
30680 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
30690 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
306a0 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ively..**.** The
306b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
306c0 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
306d0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
306e0 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
306f0 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
30700 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
30710 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
30720 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
30730 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
30740 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
30750 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
30760 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
30770 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
30780 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
30790 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
307a0 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
307b0 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
307c0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
307d0 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
307e0 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
307f0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
30800 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
30810 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
30820 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
30830 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
30840 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
30850 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
30860 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
30870 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c  turned..**.** Pl
30880 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
30890 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
308a0 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
308b0 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
308c0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
308d0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
308e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
308f0 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
30900 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
30910 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
30920 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
30930 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
30940 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
30950 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
30960 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
30970 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
30980 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30990 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
309a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
309b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
309c0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
309d0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
309e0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
309f0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
30a00 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
30a10 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
30a20 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
30a30 72 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  rs..**.** INVARI
30a40 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ANTS:.**.** {H15
30a50 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  103} The [sqlite
30a60 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d  3_value_blob(V)]
30a70 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
30a80 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
30a90 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
30aa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30ab0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 42 4c  ject V into a BL
30ac0 4f 42 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 20  OB and then.**  
30ad0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
30ae0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
30af0 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65   converted value
30b00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 7d  ..**.** {H15106}
30b10 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
30b20 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e  lue_bytes(V)] in
30b30 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
30b40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
30b50 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
30b60 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  in the BLOB or s
30b70 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
30b80 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
30b90 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
30ba0 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
30bb0 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
30bc0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
30bd0 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
30be0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
30bf0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
30c00 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  V)] or.**       
30c10 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75     [sqlite3_valu
30c20 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a  e_text(V)]..**.*
30c30 2a 20 7b 48 31 35 31 30 39 7d 20 54 68 65 20 5b  * {H15109} The [
30c40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
30c50 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66  tes16(V)] interf
30c60 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
30c70 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
30c80 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
30c90 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  he string (exclu
30ca0 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
30cb0 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
30cc0 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
30cd0 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
30ce0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
30cf0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
30d00 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
30d10 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30d20 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20  ext16(V)],.**   
30d30 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
30d40 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56  value_text16be(V
30d50 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
30d60 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56  value_text16le(V
30d70 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31  )]..**.** {H1511
30d80 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
30d90 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d  value_double(V)]
30da0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
30db0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
30dc0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
30dd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30de0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c  ject V into a fl
30df0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
30e00 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ue and.**       
30e10 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
30e20 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e  y of that value.
30e30 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d 20  .**.** {H15115} 
30e40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
30e50 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72  ue_int(V)] inter
30e60 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
30e70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
30e80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30e90 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
30ea0 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
30eb0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
30ec0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
30ed0 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20  turns the lower 
30ee0 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20  32 bits of that 
30ef0 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
30f00 48 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c  H15118} The [sql
30f10 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
30f20 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
30f30 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
30f40 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
30f50 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30f60 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
30f70 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
30f80 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20  integer and.**  
30f90 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20          returns 
30fa0 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69  a copy of that i
30fb0 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nteger..**.** {H
30fc0 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  15121} The [sqli
30fd0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56  te3_value_text(V
30fe0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
30ff0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
31000 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
31010 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
31020 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
31030 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
31040 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20  UTF-8.**        
31050 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
31060 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
31070 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
31080 2a 0a 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54 68  *.** {H15124} Th
31090 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
310a0 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65  _text16(V)] inte
310b0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
310c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
310d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
310e0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
310f0 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
31100 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
31110 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
31120 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ned UTF-16 nativ
31130 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
31140 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
31150 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
31160 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
31170 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
31180 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  127} The [sqlite
31190 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
311a0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
311b0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
311c0 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
311d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
311e0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
311f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
31200 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
31210 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
31220 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a  -16 big-endian.*
31230 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
31240 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
31250 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
31260 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
31270 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69  15130} The [sqli
31280 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31290 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  le(V)] interface
312a0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
312b0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
312c0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
312d0 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
312e0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
312f0 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
31300 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
31310 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64  TF-16 little-end
31320 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ian.**          
31330 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
31340 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
31350 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
31360 2a 2a 20 7b 48 31 35 31 33 33 7d 20 54 68 65 20  ** {H15133} The 
31370 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
31380 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ype(V)] interfac
31390 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
313a0 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51        one of [SQ
313b0 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_NULL], [SQL
313c0 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53  ITE_INTEGER], [S
313d0 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a  QLITE_FLOAT],.**
313e0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
313f0 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c  E_TEXT], or [SQL
31400 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70  ITE_BLOB] as app
31410 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20  ropriate for.** 
31420 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
31430 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31440 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ect V..**.** {H1
31450 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  5136} The [sqlit
31460 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
31470 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66  _type(V)] interf
31480 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  ace converts.** 
31490 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
314a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
314b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
314c0 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69  into either an i
314d0 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20  nteger or.**    
314e0 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67        a floating
314f0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20   point value if 
31500 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74  it can do so wit
31510 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20  hout loss of.** 
31520 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61           informa
31530 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e  tion, and return
31540 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
31550 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20  _NULL],.**      
31560 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45      [SQLITE_INTE
31570 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c  GER], [SQLITE_FL
31580 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
31590 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  XT], or.**      
315a0 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42      [SQLITE_BLOB
315b0 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65  ] as appropriate
315c0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
315d0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
315e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
315f0 62 6a 65 63 74 20 56 20 61 66 74 65 72 20 74 68  bject V after th
31600 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74  e conversion att
31610 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  empt..*/.const v
31620 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
31630 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
31640 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
31650 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
31660 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31670 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
31680 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
31690 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
316a0 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
316b0 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
316c0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
316d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
316e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
316f0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
31700 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
31710 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
31720 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
31730 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
31740 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
31750 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
31760 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31770 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
31780 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
31790 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
317a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
317b0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
317c0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
317d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
317e0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
317f0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
31800 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
31810 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
31820 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
31830 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
31840 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
31850 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31860 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
31870 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
31880 74 20 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32  t {H16210} <S202
31890 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d  00>.**.** The im
318a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
318b0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
318c0 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
318d0 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
318e0 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74  cate.** a struct
318f0 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ure for storing 
31900 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
31910 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d  ** The first tim
31920 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
31930 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31940 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
31950 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72  led for a.** par
31960 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
31970 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61  e, SQLite alloca
31980 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65  tes nBytes of me
31990 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
319a0 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   that.** memory,
319b0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
319c0 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e  ointer to it. On
319d0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
319e0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
319f0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
31a00 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
31a10 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
31a20 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
31a30 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ndex,.** the sam
31a40 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
31a50 72 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d  rned. The implem
31a60 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
31a70 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73  aggregate can us
31a80 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65  e.** the returne
31a90 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63 75  d buffer to accu
31aa0 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a  mulate data..**.
31ab0 2a 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  ** SQLite automa
31ac0 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
31ad0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66  e allocated buff
31ae0 65 72 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  er when the aggr
31af0 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63  egate.** query c
31b00 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
31b10 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
31b20 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ter should be a 
31b30 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
31b40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
31b50 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
31b60 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
31b70 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
31b80 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
31b90 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
31ba0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
31bb0 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
31bc0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
31bd0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
31be0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
31bf0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
31c00 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
31c10 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
31c20 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
31c30 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
31c40 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 31  S:.**.** {H16211
31c50 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f  } The first invo
31c60 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
31c70 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
31c80 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a  text(C,N)] for.*
31c90 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 61 72  *          a par
31ca0 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65  ticular instance
31cb0 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61 74 65   of an aggregate
31cc0 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61   function (for a
31cd0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20   particular.**  
31ce0 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20          context 
31cf0 43 29 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  C) causes SQLite
31d00 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62   to allocate N b
31d10 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a  ytes of memory,.
31d20 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
31d30 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
31d40 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74  d return a point
31d50 65 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61  er to the alloca
31d60 74 65 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a  ted memory..**.*
31d70 2a 20 7b 48 31 36 32 31 33 7d 20 49 66 20 61 20  * {H16213} If a 
31d80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
31d90 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
31da0 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  uring.**        
31db0 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65    [sqlite3_aggre
31dc0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
31dd0 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63  )] then the func
31de0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a  tion returns 0..
31df0 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 35 7d 20 53  **.** {H16215} S
31e00 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
31e10 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
31e20 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
31e30 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
31e40 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
31e50 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f   for the same co
31e60 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a  ntext pointer C.
31e70 2a 2a 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f  **          igno
31e80 72 65 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  re the N paramet
31e90 65 72 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20  er and return a 
31ea0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73  pointer to the s
31eb0 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
31ec0 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
31ed0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
31ee0 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e  first invocation
31ef0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 37 7d  ..**.** {H16217}
31f00 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
31f10 63 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  cated by [sqlite
31f20 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31f30 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20  ext(C,N)] is.** 
31f40 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74           automat
31f50 69 63 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20  ically freed on 
31f60 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
31f70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31f80 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
31f90 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
31fa0 69 7a 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b  ize()] for the [
31fb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31fc0 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a  nt] containing.*
31fd0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
31fe0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
31ff0 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  n associated wit
32000 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a  h context C..*/.
32010 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
32020 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
32030 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32040 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
32050 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32060 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
32070 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d  nctions {H16240}
32080 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
32090 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
320a0 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
320b0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
320c0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
320d0 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
320e0 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
320f0 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
32100 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
32110 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
32120 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
32130 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
32140 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
32150 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
32160 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
32170 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
32180 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
32190 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44  d function. {END
321a0 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
321b0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
321c0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
321d0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
321e0 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
321f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32200 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
32210 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
32220 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34  TS:.**.** {H1624
32230 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
32240 75 73 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e  user_data(C)] in
32250 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
32260 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
32270 20 20 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e            P poin
32280 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ter from the [sq
32290 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
322a0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
322b0 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
322c0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
322d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
322e0 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  6(D,X,N,E,P,F,S,
322f0 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a  L)] call that.**
32300 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
32310 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e  ered the SQL fun
32320 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64  ction associated
32330 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63   with [sqlite3_c
32340 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f  ontext] C..*/.vo
32350 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
32360 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
32370 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
32380 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
32390 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
323a0 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36  r Functions {H16
323b0 32 35 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32  250} <S60600><S2
323c0 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
323d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
323e0 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
323f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
32400 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
32410 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
32420 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
32430 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
32440 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
32450 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
32460 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
32470 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
32480 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
32490 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
324a0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
324b0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
324c0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
324d0 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
324e0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
324f0 0a 2a 2a 20 7b 48 31 36 32 35 33 7d 20 54 68 65  .** {H16253} The
32500 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
32510 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20  t_db_handle(C)] 
32520 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
32530 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
32540 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 70 6f  **          D po
32550 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b  inter from the [
32560 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32570 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
32580 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20  P,F,S,L)].**    
32590 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
325a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
325b0 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  n16(D,X,N,E,P,F,
325c0 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a  S,L)] call that.
325d0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
325e0 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20 66  stered the SQL f
325f0 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74  unction associat
32600 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
32610 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a  _context] C..*/.
32620 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
32630 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
32640 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
32650 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
32660 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
32670 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b  Auxiliary Data {
32680 48 31 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e  H16270} <S20200>
32690 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
326a0 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
326b0 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
326c0 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  y scalar SQL fun
326d0 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
326e0 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
326f0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
32700 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
32710 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
32720 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
32730 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
32740 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
32750 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
32760 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
32770 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
32780 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
32790 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
327a0 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
327b0 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
327c0 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
327d0 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
327e0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
327f0 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
32800 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
32810 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
32820 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
32830 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
32840 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
32850 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
32860 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76  d with the SQL v
32870 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
32880 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
32890 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e  ssion.** pattern
328a0 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  .  The compiled 
328b0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
328c0 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
328d0 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
328e0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
328f0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
32900 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69   so that the ori
32910 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74  ginal pattern st
32920 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ring.** does not
32930 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f   need to be reco
32940 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69  mpiled on each i
32950 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
32960 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
32970 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
32980 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
32990 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
329a0 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
329b0 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
329c0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
329d0 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
329e0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
329f0 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
32a00 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32a10 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49  ined function. I
32a20 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61  f no metadata ha
32a30 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62  s been ever.** b
32a40 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
32a50 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  Nth argument of 
32a60 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72  the function, or
32a70 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   if the correspo
32a80 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  nding.** functio
32a90 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  n parameter has 
32aa0 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68  changed since th
32ab0 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20  e meta-data was 
32ac0 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  set,.** then sql
32ad0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
32ae0 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
32af0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
32b00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   The sqlite3_set
32b10 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
32b20 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d  face saves the m
32b30 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74  etadata.** point
32b40 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64  ed to by its 3rd
32b50 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
32b60 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  e metadata for t
32b70 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
32b80 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
32b90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
32ba0 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71  unction.  Subseq
32bb0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
32bc0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
32bd0 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74  data() might ret
32be0 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69  urn this data, i
32bf0 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20  f it has.** not 
32c00 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a  been destroyed..
32c10 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20  ** If it is not 
32c20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
32c30 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
32c40 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
32c50 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
32c60 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
32c70 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
32c80 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
32c90 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
32ca0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
32cb0 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
32cc0 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
32cd0 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
32ce0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
32cf0 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
32d00 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
32d10 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
32d20 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
32d30 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
32d40 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
32d50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
32d60 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
32d70 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20   any time.  The 
32d80 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
32d90 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
32da0 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
32db0 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
32dc0 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
32dd0 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ropped..**.** In
32de0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
32df0 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
32e00 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
32e10 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65  n calls for.** e
32e20 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20  xpressions that 
32e30 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20  are constant at 
32e40 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68  compile time. Th
32e50 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65  is includes lite
32e60 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e  ral.** values an
32e70 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e  d SQL variables.
32e80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
32e90 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
32ea0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
32eb0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
32ec0 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
32ed0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
32ee0 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  g..**.** INVARIA
32ef0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  NTS:.**.** {H162
32f00 37 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  72} The [sqlite3
32f10 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _get_auxdata(C,N
32f20 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
32f30 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
32f40 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65  *          to me
32f50 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
32f60 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 70  d with the Nth p
32f70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
32f80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  SQL function.** 
32f90 20 20 20 20 20 20 20 20 20 77 68 6f 73 65 20 63           whose c
32fa0 6f 6e 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20  ontext is C, or 
32fb0 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73  NULL if there is
32fc0 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73   no metadata ass
32fd0 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  ociated.**      
32fe0 20 20 20 20 77 69 74 68 20 74 68 61 74 20 70 61      with that pa
32ff0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
33000 48 31 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c  H16274} The [sql
33010 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33020 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72  (C,N,P,D)] inter
33030 66 61 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d  face assigns a m
33040 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20  etadata.**      
33050 20 20 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f      pointer P to
33060 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74   the Nth paramet
33070 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  er of the SQL fu
33080 6e 63 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74  nction with cont
33090 65 78 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ext C..**.** {H1
330a0 36 32 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c  6276} SQLite wil
330b0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
330c0 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 61  tructor D with a
330d0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
330e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69  .**          whi
330f0 63 68 20 69 73 20 74 68 65 20 6d 65 74 61 64 61  ch is the metada
33100 74 61 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c  ta pointer P fol
33110 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
33120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
33130 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33140 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e  a(C,N,P,D)] when
33150 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74   SQLite ceases t
33160 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20  o hold.**       
33170 20 20 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e     the metadata.
33180 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 37 7d 20  .**.** {H16277} 
33190 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f  SQLite ceases to
331a0 20 68 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66   hold metadata f
331b0 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  or an SQL functi
331c0 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  on parameter.** 
331d0 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 74 68           when th
331e0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
331f0 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
33200 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 38  s..**.** {H16278
33210 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  } When [sqlite3_
33220 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
33230 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  P,D)] is invoked
33240 2c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  , the destructor
33250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
33260 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70  called for any p
33270 72 69 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73  rior metadata as
33280 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
33290 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
332a0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
332b0 65 78 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65  ext C and parame
332c0 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ter N..**.** {H1
332d0 36 32 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c  6279} SQLite wil
332e0 6c 20 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f  l call destructo
332f0 72 73 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64  rs for any metad
33300 61 74 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e  ata it is holdin
33310 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  g.**          in
33320 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70   a particular [p
33330 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33340 74 5d 20 53 20 77 68 65 6e 20 65 69 74 68 65 72  t] S when either
33350 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
33360 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
33370 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
33380 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c  lize(S)] is call
33390 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ed..*/.void *sql
333a0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
333b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
333c0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20  *, int N);.void 
333d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
333e0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
333f0 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69  ext*, int N, voi
33400 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69  d*, void (*)(voi
33410 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*));.../*.** CA
33420 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74  PI3REF: Constant
33430 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69  s Defining Speci
33440 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65  al Destructor Be
33450 68 61 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20  havior {H10280} 
33460 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
33470 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
33480 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
33490 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
334a0 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
334b0 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
334c0 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
334d0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
334e0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
334f0 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74   If the destruct
33500 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
33510 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
33520 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
33530 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
33540 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
33550 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
33560 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
33570 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
33580 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65   destroyed.  The
33590 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  .** SQLITE_TRANS
335a0 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73  IENT value means
335b0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
335c0 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68  t will likely ch
335d0 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e  ange in.** the n
335e0 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74  ear future and t
335f0 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c  hat SQLite shoul
33600 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70  d make its own p
33610 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a  rivate copy of.*
33620 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65  * the content be
33630 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a  fore returning..
33640 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65  **.** The typede
33650 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74  f is necessary t
33660 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72  o work around pr
33670 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69  oblems in certai
33680 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65  n.** C++ compile
33690 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20  rs.  See ticket 
336a0 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65  #2191..*/.typede
336b0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
336c0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
336d0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
336e0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
336f0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
33700 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
33710 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
33720 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
33730 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
33740 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
33750 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
33760 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
33770 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
33780 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32  n {H16400} <S202
33790 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
337a0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
337b0 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
337c0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
337d0 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
337e0 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
337f0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
33800 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
33810 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33820 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
33830 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33840 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
33850 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
33860 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
33870 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
33880 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
33890 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
338a0 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
338b0 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
338c0 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
338d0 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
338e0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
338f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
33900 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
33910 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
33920 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
33930 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
33940 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
33950 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33960 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
33970 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
33980 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
33990 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
339a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
339b0 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
339c0 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
339d0 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
339e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
339f0 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
33a00 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
33a10 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
33a20 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
33a30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
33a40 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
33a50 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
33a60 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
33a70 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
33a80 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33a90 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
33aa0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
33ab0 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
33ac0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
33ad0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
33ae0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
33af0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
33b00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
33b10 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
33b20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
33b30 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
33b40 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
33b50 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
33b60 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
33b70 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
33b80 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
33b90 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
33ba0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
33bb0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
33bc0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
33bd0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
33be0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
33bf0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
33c00 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
33c10 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
33c20 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  tion..** SQLite 
33c30 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20  uses the string 
33c40 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
33c50 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74  e.** 2nd paramet
33c60 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65  er of sqlite3_re
33c70 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20  sult_error() or 
33c80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33c90 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74  rror16().** as t
33ca0 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72  he text of an er
33cb0 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51  ror message.  SQ
33cc0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
33cd0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
33ce0 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
33cf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33d00 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
33d10 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65  . SQLite.** inte
33d20 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
33d30 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
33d40 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
33d50 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
33d60 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
33d70 72 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  r.  If the third
33d80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
33d90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33da0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
33db0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
33dc0 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
33dd0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
33de0 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
33df0 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
33e00 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
33e10 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
33e20 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68  racter..** If th
33e30 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
33e40 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
33e50 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
33e60 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
33e70 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
33e80 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
33e90 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
33ea0 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
33eb0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
33ec0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
33ed0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
33ee0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
33ef0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
33f00 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
33f10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33f20 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
33f30 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
33f40 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
33f50 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
33f60 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
33f70 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
33f80 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
33f90 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
33fa0 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
33fb0 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
33fc0 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
33fd0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54  thout harm..** T
33fe0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33ff0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
34000 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
34010 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
34020 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
34030 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
34040 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
34050 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20  a function.  By 
34060 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
34070 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
34080 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73  LITE_ERROR.  A s
34090 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
340a0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
340b0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
340c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
340d0 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
340e0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
340f0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
34100 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
34110 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
34120 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
34130 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
34140 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
34150 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
34160 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
34170 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70  s to long to rep
34180 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  resent..**.** Th
34190 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
341a0 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
341b0 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
341c0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
341d0 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
341e0 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
341f0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
34200 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
34210 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
34220 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
34230 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
34240 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
34250 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34260 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
34270 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
34280 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
34290 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
342a0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  d argument..** T
342b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
342c0 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
342d0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
342e0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
342f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34300 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34310 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
34320 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
34330 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
34340 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
34350 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ent..**.** The s
34360 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
34370 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
34380 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
34390 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
343a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
343b0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
343c0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  e NULL..**.** Th
343d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
343e0 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
343f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
34400 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  ,.** sqlite3_res
34410 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20  ult_text16le(), 
34420 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
34430 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e  lt_text16be() in
34440 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20  terfaces.** set 
34450 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
34460 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
34470 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34480 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
34490 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63  text string whic
344a0 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  h is represented
344b0 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31   as UTF-8, UTF-1
344c0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
344d0 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  der,.** UTF-16 l
344e0 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72  ittle endian, or
344f0 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69   UTF-16 big endi
34500 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
34510 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65  ..** SQLite take
34520 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c  s the text resul
34530 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69  t from the appli
34540 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74  cation from.** t
34550 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
34560 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
34570 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
34580 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74  erfaces..** If t
34590 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
345a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
345b0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
345c0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
345d0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
345e0 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
345f0 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
34600 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
34610 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
34620 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
34630 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
34640 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
34650 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34660 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34670 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
34680 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
34690 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
346a0 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
346b0 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
346c0 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
346d0 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
346e0 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
346f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
34700 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
34710 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
34720 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
34730 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34740 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
34750 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
34760 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
34770 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
34780 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
34790 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
347a0 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
347b0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
347c0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
347d0 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
347e0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
347f0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
34800 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
34810 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
34820 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
34830 69 6e 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a  interfaces or.**
34840 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34850 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
34860 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
34870 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
34880 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
34890 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
348a0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
348b0 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
348c0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
348d0 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74  t.** copy the it
348e0 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72   or call a destr
348f0 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61  uctor when it ha
34900 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
34910 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
34920 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61   If the 4th para
34930 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
34940 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34950 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
34960 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
34970 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
34980 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
34990 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
349a0 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
349b0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
349c0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
349d0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
349e0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
349f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
34a00 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
34a10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
34a20 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
34a30 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
34a40 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
34a50 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
34a60 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34a70 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
34a80 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
34a90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34aa0 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
34ab0 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
34ac0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a  arameter.  The.*
34ad0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
34ae0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
34af0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
34b00 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
34b10 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
34b20 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
34b30 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
34b40 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
34b50 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
34b60 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
34b70 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
34b80 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
34b90 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
34ba0 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63  rm..** A [protec
34bb0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34bc0 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
34bd0 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
34be0 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
34bf0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
34c00 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
34c10 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
34c20 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
34c30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34c40 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
34c50 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
34c60 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
34c70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
34c80 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
34c90 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
34ca0 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
34cb0 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
34cc0 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
34cd0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34ce0 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
34cf0 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
34d00 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
34d10 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
34d20 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
34d30 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
34d40 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 33  S:.**.** {H16403
34d50 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 72 65  } The default re
34d60 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
34d70 61 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  any SQL function
34d80 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
34d90 7b 48 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71  {H16406} The [sq
34da0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
34db0 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  b(C,V,N,D)] inte
34dc0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
34dd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
34de0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
34df0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
34e00 20 42 4c 4f 42 20 74 68 61 74 20 69 73 20 4e 20   BLOB that is N 
34e10 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  bytes.**        
34e20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20    in length and 
34e30 77 69 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69  with content poi
34e40 6e 74 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a  nted to by V..**
34e50 0a 2a 2a 20 7b 48 31 36 34 30 39 7d 20 54 68 65  .** {H16409} The
34e60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
34e70 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e  _double(C,V)] in
34e80 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
34e90 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
34ea0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
34eb0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
34ec0 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
34ed0 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a  int value V..**.
34ee0 2a 2a 20 7b 48 31 36 34 31 32 7d 20 54 68 65 20  ** {H16412} The 
34ef0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
34f00 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e  error(C,V,N)] in
34f10 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
34f20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
34f30 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
34f40 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
34f50 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
34f60 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  th error code.**
34f70 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
34f80 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55  E_ERROR] and a U
34f90 54 46 2d 38 20 65 72 72 6f 72 20 6d 65 73 73 61  TF-8 error messa
34fa0 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56  ge copied from V
34fb0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20   up to the.**   
34fc0 20 20 20 20 20 20 20 66 69 72 73 74 20 7a 65 72         first zer
34fd0 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20  o byte or until 
34fe0 4e 20 62 79 74 65 73 20 61 72 65 20 72 65 61 64  N bytes are read
34ff0 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
35000 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 35  e..**.** {H16415
35010 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
35020 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c  esult_error16(C,
35030 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  V,N)] interface 
35040 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75  changes the retu
35050 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  rn.**          v
35060 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
35070 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
35080 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
35090 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
350a0 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d    [SQLITE_ERROR]
350b0 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 6e 61   and a UTF-16 na
350c0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
350d0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
350e0 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 64            copied
350f0 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68   from V up to th
35100 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
35110 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c  minator or until
35120 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
35130 20 20 20 20 20 61 72 65 20 72 65 61 64 20 69 66       are read if
35140 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a   N is positive..
35150 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 38 7d 20 54  **.** {H16418} T
35160 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
35170 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
35180 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
35190 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
351a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
351b0 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
351c0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
351d0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
351e0 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
351f0 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42      [SQLITE_TOOB
35200 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  IG] and an appro
35210 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
35220 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  sage..**.** {H16
35230 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  421} The [sqlite
35240 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
35250 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61  omem(C)] interfa
35260 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
35270 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
35280 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
35290 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
352a0 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
352b0 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
352c0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
352d0 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61  _NOMEM] and an a
352e0 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
352f0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
35300 7b 48 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71  {H16424} The [sq
35310 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35320 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e  or_code(C,E)] in
35330 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
35340 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  the return.**   
35350 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
35360 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74  the function C t
35370 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
35380 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
35390 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  e E..**         
353a0 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   The error messa
353b0 67 65 20 74 65 78 74 20 69 73 20 75 6e 63 68 61  ge text is uncha
353c0 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  nged..**.** {H16
353d0 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  427} The [sqlite
353e0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56  3_result_int(C,V
353f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
35400 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
35410 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
35420 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
35430 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
35440 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56   integer value V
35450 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 30 7d  ..**.** {H16430}
35460 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
35470 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d  sult_int64(C,V)]
35480 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
35490 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
354a0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
354b0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
354c0 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 69   be the 64-bit i
354d0 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
354e0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 33 7d 20 54  **.** {H16433} T
354f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
35500 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65  lt_null(C)] inte
35510 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
35520 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
35530 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
35540 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e  nction C to be N
35550 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ULL..**.** {H164
35560 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
35570 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
35580 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
35590 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
355a0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
355b0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
355c0 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
355d0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  F-8 string.**   
355e0 20 20 20 20 20 20 20 56 20 75 70 20 74 6f 20 74         V up to t
355f0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66  he first zero if
35600 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   N is negative.*
35610 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
35620 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20  e first N bytes 
35630 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e  of V if N is non
35640 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a  -negative..**.**
35650 20 7b 48 31 36 34 33 39 7d 20 54 68 65 20 5b 73   {H16439} The [s
35660 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35670 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  xt16(C,V,N,D)] i
35680 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
35690 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
356a0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
356b0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
356c0 65 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74  e the UTF-16 nat
356d0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
356e0 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
356f0 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69  g V up to the fi
35700 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73  rst zero if N is
35710 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20   negative.**    
35720 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72        or the fir
35730 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20  st N bytes of V 
35740 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  if N is non-nega
35750 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tive..**.** {H16
35760 34 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  442} The [sqlite
35770 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
35780 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65  e(C,V,N,D)] inte
35790 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
357a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
357b0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
357c0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
357d0 68 65 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  he UTF-16 big-en
357e0 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
357f0 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20   string V up to 
35800 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69  the first zero i
35810 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a  f N is negative.
35820 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
35830 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
35840 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   or V if N is no
35850 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
35860 2a 20 7b 48 31 36 34 34 35 7d 20 54 68 65 20 5b  * {H16445} The [
35870 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35880 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29  ext16le(C,V,N,D)
35890 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
358a0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
358b0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
358c0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
358d0 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20  o be the UTF-16 
358e0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a  little-endian.**
358f0 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
35900 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
35910 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20  st zero if N is 
35920 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
35930 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73       or the firs
35940 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69  t N bytes of V i
35950 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
35960 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ive..**.** {H164
35970 34 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  48} The [sqlite3
35980 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c  _result_value(C,
35990 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
359a0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
359b0 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
359c0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
359d0 20 74 6f 20 62 65 20 74 68 65 20 5b 75 6e 70 72   to be the [unpr
359e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
359f0 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20  value].**       
35a00 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a     object V..**.
35a10 2a 2a 20 7b 48 31 36 34 35 31 7d 20 54 68 65 20  ** {H16451} The 
35a20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35a30 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69  zeroblob(C,N)] i
35a40 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
35a50 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
35a60 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
35a70 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
35a80 65 20 61 6e 20 4e 2d 62 79 74 65 20 42 4c 4f 42  e an N-byte BLOB
35a90 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a   of all zeros..*
35aa0 2a 0a 2a 2a 20 7b 48 31 36 34 35 34 7d 20 54 68  *.** {H16454} Th
35ab0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
35ac0 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b  t_error()] and [
35ad0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35ae0 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20  rror16()].**    
35af0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
35b00 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
35b10 74 68 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73  their error mess
35b20 61 67 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f  age strings befo
35b30 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  re.**          r
35b40 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
35b50 7b 48 31 36 34 35 37 7d 20 49 66 20 74 68 65 20  {H16457} If the 
35b60 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72  D destructor par
35b70 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
35b80 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43  e3_result_blob(C
35b90 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
35ba0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
35bb0 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
35bc0 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72  ,D)], [sqlite3_r
35bd0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56  esult_text16(C,V
35be0 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
35bf0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
35c00 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56  ult_text16be(C,V
35c10 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,N,D)], or.**   
35c20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
35c30 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
35c40 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65  C,V,N,D)] is the
35c50 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
35c60 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20  E_STATIC].**    
35c70 20 20 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65        then no de
35c80 73 74 72 75 63 74 6f 72 20 69 73 20 65 76 65 72  structor is ever
35c90 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70   called on the p
35ca0 6f 69 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c  ointer V and SQL
35cb0 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ite.**          
35cc0 61 73 73 75 6d 65 73 20 74 68 61 74 20 56 20 69  assumes that V i
35cd0 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a  s immutable..**.
35ce0 2a 2a 20 7b 48 31 36 34 36 30 7d 20 49 66 20 74  ** {H16460} If t
35cf0 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
35d00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
35d10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
35d20 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
35d30 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
35d40 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
35d50 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
35d60 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
35d70 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
35d80 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
35d90 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
35da0 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
35db0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
35dc0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35dd0 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
35de0 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20  the constant.** 
35df0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
35e00 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e  _TRANSIENT] then
35e10 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
35e20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
35e30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
35e40 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64  content of V and
35e50 20 72 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70   retains the cop
35e60 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 33  y..**.** {H16463
35e70 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
35e80 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
35e90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
35ea0 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
35eb0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
35ec0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35ed0 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
35ee0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35ef0 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
35f00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
35f10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35f20 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
35f30 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
35f40 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35f50 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
35f60 29 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65  )] is some value
35f70 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
35f80 20 20 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73          the cons
35f90 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54  tants [SQLITE_ST
35fa0 41 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATIC] and [SQLIT
35fb0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65  E_TRANSIENT] the
35fc0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  n.**          SQ
35fd0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
35fe0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
35ff0 44 20 77 69 74 68 20 56 20 61 73 20 69 74 73 20  D with V as its 
36000 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  only argument.**
36010 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 69            when i
36020 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
36030 69 74 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e  ith the V value.
36040 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
36050 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
36060 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
36070 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
36080 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
36090 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
360a0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
360b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
360c0 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
360d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
360e0 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
360f0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
36100 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
36110 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36120 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
36130 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36140 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
36150 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36160 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
36170 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
36180 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36190 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
361a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
361b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
361c0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
361d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
361e0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
361f0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
36200 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36210 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
36220 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
36230 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36240 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
36250 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36260 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
36270 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
36280 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36290 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
362a0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
362b0 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
362c0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
362d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
362e0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
362f0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
36300 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
36310 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
36320 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36330 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
36340 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
36350 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
36360 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
36370 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36380 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
36390 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
363a0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
363b0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
363c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
363d0 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
363e0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
363f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
36400 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
36410 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
36420 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
36430 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36440 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
36450 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
36460 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33  s {H16600} <S203
36470 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
36480 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73  functions are us
36490 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f  ed to add new co
364a0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
364b0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74  s to the.** [dat
364c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
364d0 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74  ] specified as t
364e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
364f0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d  t..**.** The nam
36500 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c  e of the new col
36510 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
36520 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20  is specified as 
36530 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
36540 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
36550 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
36560 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
36570 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
36580 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
36590 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71  16 string for sq
365a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
365b0 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61  lation16(). In a
365c0 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20  ll cases.** the 
365d0 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61  name is passed a
365e0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
365f0 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
36600 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
36610 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
36620 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
36630 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
36640 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
36650 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49  TF16LE] or [SQLI
36660 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64  TE_UTF16BE], ind
36670 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65  icating that the
36680 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a   user-supplied.*
36690 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  * routine expect
366a0 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70  s to be passed p
366b0 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
366c0 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  gs encoded using
366d0 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31   UTF-8,.** UTF-1
366e0 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c  6 little-endian,
366f0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65   or UTF-16 big-e
36700 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
36710 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72  ely. The.** thir
36720 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74  d argument might
36730 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45   also be [SQLITE
36740 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
36750 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
36760 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20  .** the routine 
36770 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73  expects pointers
36780 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20   to 16-bit word 
36790 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a  aligned strings.
367a0 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20  ** of UTF-16 in 
367b0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
367c0 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
367d0 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a  t computer..**.*
367e0 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
367f0 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64  he user supplied
36800 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
36810 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
36820 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ifth.** argument
36830 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  .  If it is NULL
36840 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61  , this is the sa
36850 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74  me as deleting t
36860 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  he collation.** 
36870 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61  sequence (so tha
36880 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20  t SQLite cannot 
36890 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29  call it anymore)
368a0 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74  ..** Each time t
368b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
368c0 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e  upplied function
368d0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20   is invoked, it 
368e0 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20  is passed.** as 
368f0 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  its first parame
36900 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ter a copy of th
36910 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61  e void* passed a
36920 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  s the fourth arg
36930 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
36940 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36950 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
36960 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36970 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  on16()..**.** Th
36980 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
36990 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70  ments to the app
369a0 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
369b0 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
369c0 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
369d0 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
369e0 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74  y a (length, dat
369f0 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a) pair and enco
36a00 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
36a10 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
36a20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
36a30 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
36a40 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
36a50 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
36a60 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44  registered. {END
36a70 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  }  The applicati
36a80 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61  on defined colla
36a90 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f  tion routine sho
36aa0 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65  uld.** return ne
36ab0 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20  gative, zero or 
36ac0 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 20  positive if the 
36ad0 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
36ae0 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71  less than,.** eq
36af0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
36b00 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
36b10 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20  nd string. i.e. 
36b20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e  (STRING1 - STRIN
36b30 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  G2)..**.** The s
36b40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36b50 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72  llation_v2() wor
36b60 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
36b70 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36b80 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
36b90 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78  t it takes an ex
36ba0 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69  tra argument whi
36bb0 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74  ch is a destruct
36bc0 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f  or for.** the co
36bd0 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  llation.  The de
36be0 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
36bf0 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  ed when the coll
36c00 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74  ation is.** dest
36c10 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73  royed and is pas
36c20 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68  sed a copy of th
36c30 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
36c40 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  er void* pointer
36c50 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
36c60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36c70 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c  ion_v2()..** Col
36c80 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74  lations are dest
36c90 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 20  royed when they 
36ca0 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
36cb0 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f  y later calls to
36cc0 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f   the.** collatio
36cd0 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
36ce0 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
36cf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36d00 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
36d10 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
36d20 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
36d30 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
36d40 2a 0a 2a 2a 20 7b 48 31 36 36 30 33 7d 20 41 20  *.** {H16603} A 
36d50 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
36d60 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
36d70 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
36d80 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
36d90 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e  B,X,E,P,F,D)] in
36da0 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20  terface.**      
36db0 20 20 20 20 72 65 67 69 73 74 65 72 73 20 66 75      registers fu
36dc0 6e 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20  nction F as the 
36dd0 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
36de0 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20  ion used to.**  
36df0 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e          implemen
36e00 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e  t collation X on
36e10 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
36e20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72  onnection] B for
36e30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74  .**          dat
36e40 61 62 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e  abases having en
36e50 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20  coding E..**.** 
36e60 7b 48 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20  {H16604} SQLite 
36e70 75 6e 64 65 72 73 74 61 6e 64 73 20 74 68 65 20  understands the 
36e80 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  X parameter to.*
36e90 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
36ea0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36eb0 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
36ec0 46 2c 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d  F,D)] as a zero-
36ed0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
36ee0 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
36ef0 69 6e 67 20 69 6e 20 77 68 69 63 68 20 63 61 73  ing in which cas
36f00 65 20 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72  e is ignored for
36f10 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72   ASCII character
36f20 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  s and.**        
36f30 20 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74    is significant
36f40 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63   for non-ASCII c
36f50 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
36f60 20 7b 48 31 36 36 30 36 7d 20 53 75 63 63 65 73   {H16606} Succes
36f70 73 69 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  sive calls to [s
36f80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36f90 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
36fa0 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20  ,P,F,D)].**     
36fb0 20 20 20 20 20 77 69 74 68 20 74 68 65 20 73 61       with the sa
36fc0 6d 65 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c  me values for B,
36fd0 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72   X, and E, overr
36fe0 69 64 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73  ide prior values
36ff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
37000 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a  P, F, and D..**.
37010 2a 2a 20 7b 48 31 36 36 30 39 7d 20 49 66 20 74  ** {H16609} If t
37020 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
37030 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  in [sqlite3_crea
37040 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
37050 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a  B,X,E,P,F,D)].**
37060 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74            is not
37070 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73   NULL then it is
37080 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67   called with arg
37090 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65  ument P when the
370a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
370b0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
370c0 69 73 20 64 72 6f 70 70 65 64 20 62 79 20 53 51  is dropped by SQ
370d0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  Lite..**.** {H16
370e0 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67  612} A collating
370f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f   function is dro
37100 70 70 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  pped when it is 
37110 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a  overloaded..**.*
37120 2a 20 7b 48 31 36 36 31 35 7d 20 41 20 63 6f 6c  * {H16615} A col
37130 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37140 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20  is dropped when 
37150 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
37160 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
37170 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73      is closed us
37180 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
37190 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  se()]..**.** {H1
371a0 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65  6618} The pointe
371b0 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  r P in [sqlite3_
371c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
371d0 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
371e0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
371f0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
37200 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
37210 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
37220 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20  mparison.**     
37230 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20       function F 
37240 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65  for all subseque
37250 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
37260 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  f F..**.** {H166
37270 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  21} A call to [s
37280 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37290 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c  llation(B,X,E,P,
372a0 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a  F)] is exactly.*
372b0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
372c0 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f  ame as a call to
372d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
372e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
372f0 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
37300 20 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d    the same param
37310 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c  eters and a NULL
37320 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a   destructor..**.
37330 2a 2a 20 7b 48 31 36 36 32 34 7d 20 46 6f 6c 6c  ** {H16624} Foll
37340 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33  owing a [sqlite3
37350 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37360 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
37370 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
37380 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
37390 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
373a0 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65  ion F for all te
373b0 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a  xt comparison.**
373c0 20 20 20 20 20 20 20 20 20 20 6f 70 65 72 61 74            operat
373d0 69 6f 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74  ions on the [dat
373e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
373f0 5d 20 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75  ] B on text valu
37400 65 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  es that.**      
37410 20 20 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c      use the coll
37420 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e  ating sequence n
37430 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48  amed X..**.** {H
37440 31 36 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  16627} The [sqli
37450 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37460 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46  tion16(B,X,E,P,F
37470 29 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d  )] works the sam
37480 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  e.**          as
37490 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
374a0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45  _collation(B,X,E
374b0 2c 50 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68  ,P,F)] except th
374c0 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  at the.**       
374d0 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d     collation nam
374e0 65 20 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f  e X is understoo
374f0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e  d as UTF-16 in n
37500 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
37510 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73  .**          ins
37520 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a  tead of UTF-8..*
37530 2a 0a 2a 2a 20 7b 48 31 36 36 33 30 7d 20 57 68  *.** {H16630} Wh
37540 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70  en multiple comp
37550 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  arison functions
37560 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66   are available f
37570 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  or the same.**  
37580 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
37590 67 20 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69  g sequence, SQLi
375a0 74 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f  te chooses the o
375b0 6e 65 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e  ne whose text en
375c0 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  coding.**       
375d0 20 20 20 72 65 71 75 69 72 65 73 20 74 68 65 20     requires the 
375e0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
375f0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
37600 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20  the default.**  
37610 20 20 20 20 20 20 20 20 74 65 78 74 20 65 6e 63          text enc
37620 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74  oding of the dat
37630 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  abase..*/.int sq
37640 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37650 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
37660 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
37670 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
37680 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
37690 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
376a0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
376b0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
376c0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
376d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
376e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
376f0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
37700 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
37710 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
37720 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
37730 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
37740 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37750 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37760 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
37770 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
37780 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
37790 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
377a0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
377b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
377c0 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
377d0 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
377e0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
377f0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
37800 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
37810 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
37820 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
37830 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
37840 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c  backs {H16700} <
37850 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f  S20300>.**.** To
37860 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
37870 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
37880 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
37890 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
378a0 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
378b0 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
378c0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
378d0 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
378e0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
378f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37900 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20  n] to be called 
37910 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
37920 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
37930 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
37940 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  equired..**.** I
37950 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
37960 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
37970 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
37980 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
37990 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
379a0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
379b0 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
379c0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
379d0 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
379e0 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
379f0 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20  UTF-8. {H16703} 
37a00 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  If sqlite3_colla
37a10 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20  tion_needed16() 
37a20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20  is used,.** the 
37a30 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64  names are passed
37a40 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61   as UTF-16 in ma
37a50 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74  chine native byt
37a60 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61  e order..** A ca
37a70 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e  ll to either fun
37a80 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61  ction replaces a
37a90 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c  ny existing call
37aa0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  back..**.** When
37ab0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
37ac0 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
37ad0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
37ae0 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
37af0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
37b00 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
37b10 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37b20 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
37b30 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37b40 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
37b50 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
37b60 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
37b70 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
37b80 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
37b90 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
37ba0 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
37bb0 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
37bc0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
37bd0 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
37be0 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
37bf0 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
37c00 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
37c10 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
37c20 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
37c30 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
37c40 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
37c50 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
37c60 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
37c70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
37c80 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
37c90 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
37ca0 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
37cb0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
37cc0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37cd0 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
37ce0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37cf0 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
37d00 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37d10 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
37d20 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
37d30 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 32  S:.**.** {H16702
37d40 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
37d50 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37d60 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37d70 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20  (D,P,F)].**     
37d80 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
37d90 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
37da0 64 31 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73  d16(D,P,F)] caus
37db0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
37dc0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37dd0 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e  nection] D to in
37de0 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20  voke callback F 
37df0 77 69 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20  with first.**   
37e00 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
37e10 20 50 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e   P whenever it n
37e20 65 65 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f  eeds a compariso
37e30 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61  n function for a
37e40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
37e50 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20  lating sequence 
37e60 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74  that it does not
37e70 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a   know about..**.
37e80 2a 2a 20 7b 48 31 36 37 30 34 7d 20 45 61 63 68  ** {H16704} Each
37e90 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
37ea0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
37eb0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
37ec0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
37ed0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
37ee0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f  on_needed16()] o
37ef0 76 65 72 72 69 64 65 73 20 74 68 65 20 63 61 6c  verrides the cal
37f00 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 65 64  lback registered
37f10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20  .**          on 
37f20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
37f30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62  se connection] b
37f40 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f  y prior calls to
37f50 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
37f60 20 20 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a      interface..*
37f70 2a 0a 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54 68  *.** {H16706} Th
37f80 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65  e name of the re
37f90 71 75 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e  quested collatin
37fa0 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65  g function passe
37fb0 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  d in the.**     
37fc0 20 20 20 20 20 34 74 68 20 70 61 72 61 6d 65 74       4th paramet
37fd0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
37fe0 63 6b 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69  ck is in UTF-8 i
37ff0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  f the callback.*
38000 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20 72  *          was r
38010 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
38020 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
38030 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
38040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
38050 69 6e 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  in UTF-16 native
38060 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 74   byte order if t
38070 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a  he callback was.
38080 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
38090 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71  stered using [sq
380a0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
380b0 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
380c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
380d0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
380e0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
380f0 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
38100 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
38110 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
38120 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
38130 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
38140 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
38150 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
38160 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
38170 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
38180 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
38190 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70  d*).);../*.** Sp
381a0 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
381b0 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
381c0 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
381d0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
381e0 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
381f0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
38200 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
38210 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
38220 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
38230 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
38240 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
38250 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
38260 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
38270 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
38280 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
38290 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
382a0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
382b0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
382c0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
382d0 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
382e0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
382f0 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
38300 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
38310 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
38320 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
38330 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
38340 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
38350 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
38360 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
38370 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
38380 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
38390 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
383a0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
383b0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
383c0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
383d0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
383e0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
383f0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
38400 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
38410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38420 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
38430 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
38440 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
38450 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
38460 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
38470 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
38480 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
38490 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
384a0 68 6f 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33  hort Time {H1053
384b0 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a  0} <S40410>.**.*
384c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c  * The sqlite3_sl
384d0 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
384e0 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
384f0 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
38500 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
38510 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
38520 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
38530 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
38540 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
38550 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  r..**.** If the 
38560 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
38570 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
38580 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
38590 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
385a0 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
385b0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
385c0 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
385d0 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
385e0 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
385f0 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   The number of m
38600 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
38610 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
38620 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
38630 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
38640 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
38650 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
38660 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
38670 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
38680 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
38690 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
386a0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
386b0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
386c0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
386d0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 33 7d  :.**.** {H10533}
386e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c   The [sqlite3_sl
386f0 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63  eep(M)] interfac
38700 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
38710 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20  leep.**         
38720 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
38730 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
38740 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65  vfs|VFS] in orde
38750 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
38760 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
38770 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
38780 74 20 74 68 72 65 61 64 20 66 6f 72 20 61 74 20  t thread for at 
38790 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  least.**        
387a0 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73    M milliseconds
387b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 36 7d  ..**.** {H10536}
387c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c   The [sqlite3_sl
387d0 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63  eep(M)] interfac
387e0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
387f0 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20  mber of.**      
38800 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73      milliseconds
38810 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
38820 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f 66 20  ly requested of 
38830 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a  the operating.**
38840 20 20 20 20 20 20 20 20 20 20 73 79 73 74 65 6d            system
38850 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  , which might be
38860 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
38870 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f   parameter M..*/
38880 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
38890 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
388a0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
388b0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
388c0 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
388d0 69 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53  iles {H10310} <S
388e0 32 30 30 30 30 3e 0a 2a 2a