/ Hex Artifact Content
Login

Artifact 065a828e299960316aa34f05b9f0f10f33afe4c8:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69   $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 34 32 30 20 32 30 30 38 2f 31  n,v 1.420 2008/1
05f0: 32 2f 31 36 20 31 33 3a 34 36 3a 33 30 20 64 72  2/16 13:46:30 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 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
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 43 4f  define SQLITE_CO
1b880 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
1b890 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
1b8a0 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
1b8b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
1b8c0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
1b8d0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48  ing Functions {H
1b8e0 31 32 32 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a  12280} <S60400>.
1b8f0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
1b900 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1b910 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
1b920 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
1b930 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
1b940 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
1b950 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
1b960 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
1b970 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1b980 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
1b990 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1b9a0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1b9b0 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
1b9c0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
1b9d0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
1b9e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1b9f0 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
1ba00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1ba10 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
1ba20 20 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38   returns a UTF-8
1ba30 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
1ba40 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1ba50 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73  text.** as the s
1ba60 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
1ba70 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
1ba80 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c    Additional cal
1ba90 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20  lbacks occur.** 
1baa0 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
1bab0 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
1bac0 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
1bad0 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
1bae0 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
1baf0 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
1bb00 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
1bb10 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
1bb20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
1bb30 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1bb40 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1bb50 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
1bb60 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
1bb70 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
1bb80 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20   finishes.  The 
1bb90 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1bba0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
1bbb0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
1bbc0 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
1bbd0 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
1bbe0 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
1bbf0 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
1bc00 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
1bc10 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  o run..**.** INV
1bc20 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1bc30 48 31 32 32 38 31 7d 20 54 68 65 20 63 61 6c 6c  H12281} The call
1bc40 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1bc50 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c  gistered by [sql
1bc60 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 0a 2a  ite3_trace()] .*
1bc70 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
1bc80 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20   be invoked.**  
1bc90 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72          whenever
1bca0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1bcb0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74  t first begins t
1bcc0 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a  o execute and.**
1bcd0 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76            whenev
1bce0 65 72 20 61 20 74 72 69 67 67 65 72 20 73 75 62  er a trigger sub
1bcf0 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65  program first be
1bd00 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  gins to run..**.
1bd10 2a 2a 20 7b 48 31 32 32 38 32 7d 20 45 61 63 68  ** {H12282} Each
1bd20 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1bd30 33 5f 74 72 61 63 65 28 29 5d 20 73 68 61 6c 6c  3_trace()] shall
1bd40 20 6f 76 65 72 72 69 64 65 20 74 68 65 20 70 72   override the pr
1bd50 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20  eviously.**     
1bd60 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
1bd70 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  trace callback..
1bd80 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d 20 41  **.** {H12283} A
1bd90 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c   NULL trace call
1bda0 62 61 63 6b 20 73 68 61 6c 6c 20 64 69 73 61 62  back shall disab
1bdb0 6c 65 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a  le tracing..**.*
1bdc0 2a 20 7b 48 31 32 32 38 34 7d 20 54 68 65 20 66  * {H12284} The f
1bdd0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1bde0 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
1bdf0 61 63 6b 20 73 68 61 6c 6c 20 62 65 20 61 20 63  ack shall be a c
1be00 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  opy of.**       
1be10 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77     the pointer w
1be20 68 69 63 68 20 77 61 73 20 74 68 65 20 33 72 64  hich was the 3rd
1be30 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
1be40 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a  lite3_trace()]..
1be50 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54  **.** {H12285} T
1be60 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1be70 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
1be80 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a  callback is a.**
1be90 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
1bea0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1beb0 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
1bec0 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74  g the original t
1bed0 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ext.**          
1bee0 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  of the SQL state
1bef0 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70  ment as it was p
1bf00 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69  assed into [sqli
1bf10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1bf20 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
1bf30 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c   the equivalent,
1bf40 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
1bf50 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  nt indicating th
1bf60 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20  e beginning.**  
1bf70 20 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 69          of a tri
1bf80 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e  gger subprogram.
1bf90 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20  .**.** {H12287} 
1bfa0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
1bfb0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
1bfc0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f   by [sqlite3_pro
1bfd0 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b  file()] is invok
1bfe0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ed.**          a
1bff0 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
1c000 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a  ment finishes..*
1c010 2a 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20 54 68  *.** {H12288} Th
1c020 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1c030 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65  r to the profile
1c040 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
1c050 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  opy of.**       
1c060 20 20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d     the 3rd param
1c070 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1c080 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a  _profile()]..**.
1c090 2a 2a 20 7b 48 31 32 32 38 39 7d 20 54 68 65 20  ** {H12289} The 
1c0a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1c0b0 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
1c0c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a  callback is a.**
1c0d0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
1c0e0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1c0f0 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74  string that cont
1c100 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74  ains the complet
1c110 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20  e text of.**    
1c120 20 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 74        the SQL st
1c130 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61  atement as it wa
1c140 73 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b  s processed by [
1c150 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1c160 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  v2()].**        
1c170 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c    or the equival
1c180 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ent..**.** {H122
1c190 39 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 61  90} The third pa
1c1a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70  rameter to the p
1c1b0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
1c1c0 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a  is an estimate.*
1c1d0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
1c1e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f  e number of nano
1c1f0 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d  seconds of wall-
1c200 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69  clock time requi
1c210 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  red to.**       
1c220 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73     run the SQL s
1c230 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74  tatement from st
1c240 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a  art to finish..*
1c250 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  /.SQLITE_EXPERIM
1c260 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
1c270 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
1c280 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
1c290 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1c2a0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
1c2b0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
1c2c0 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
1c2d0 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
1c2e0 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
1c2f0 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
1c300 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
1c310 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
1c320 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c330 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
1c340 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31  Callbacks {H1291
1c350 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a  0} <S60400>.**.*
1c360 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
1c370 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c  onfigures a call
1c380 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20  back function - 
1c390 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20  the.** progress 
1c3a0 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20  callback - that 
1c3b0 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  is invoked perio
1c3c0 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
1c3d0 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63  ong.** running c
1c3e0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1c3f0 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
1c400 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a  e3_step()] and.*
1c410 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
1c420 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61  able()].  An exa
1c430 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
1c440 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
1c450 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
1c460 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
1c470 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
1c480 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72  .** If the progr
1c490 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
1c4a0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
1c4b0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
1c4c0 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
1c4d0 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
1c4e0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
1c4f0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
1c500 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
1c510 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
1c520 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
1c530 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
1c540 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f  dler must not do
1c550 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
1c560 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
1c570 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c580 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1c590 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
1c5a0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
1c5b0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1c5c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1c5d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1c5e0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1c5f0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1c600 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1c610 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1c620 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1c630 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1c640 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1c650 2a 2a 20 7b 48 31 32 39 31 31 7d 20 54 68 65 20  ** {H12911} The 
1c660 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c670 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1c680 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1c690 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20  _handler().**   
1c6a0 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65         is invoke
1c6b0 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
1c6c0 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
1c6d0 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20  ng calls to.**  
1c6e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1c6f0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
1c700 7b 48 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f  {H12912} The pro
1c710 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69  gress callback i
1c720 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66  s invoked once f
1c730 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72 74 75  or every N virtu
1c740 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  al.**          m
1c750 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20  achine opcodes, 
1c760 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
1c770 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
1c780 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  o.**          th
1c790 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  e [sqlite3_progr
1c7a0 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63  ess_handler()] c
1c7b0 61 6c 6c 20 74 68 61 74 20 72 65 67 69 73 74 65  all that registe
1c7c0 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
1c7d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49  the callback.  I
1c7e0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
1c7f0 20 31 2c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67   1, sqlite3_prog
1c800 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a  ress_handler().*
1c810 2a 20 20 20 20 20 20 20 20 20 20 61 63 74 73 20  *          acts 
1c820 61 73 20 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f  as if a NULL pro
1c830 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 68 61  gress handler ha
1c840 64 20 62 65 65 6e 20 73 70 65 63 69 66 69 65 64  d been specified
1c850 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d  ..**.** {H12913}
1c860 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   The progress ca
1c870 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73  llback itself is
1c880 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
1c890 68 65 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20  he third.**     
1c8a0 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f       argument to
1c8b0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1c8c0 73 5f 68 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a  s_handler()..**.
1c8d0 2a 2a 20 7b 48 31 32 39 31 34 7d 20 54 68 65 20  ** {H12914} The 
1c8e0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
1c8f0 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  to sqlite3_progr
1c900 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 20 69 73  ess_handler() is
1c910 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76   a.**          v
1c920 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73  oid pointer pass
1c930 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65  ed to the progre
1c940 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  ss callback.**  
1c950 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
1c960 20 65 61 63 68 20 74 69 6d 65 20 69 74 20 69 73   each time it is
1c970 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
1c980 7b 48 31 32 39 31 35 7d 20 49 66 20 61 20 63 61  {H12915} If a ca
1c990 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
1c9a0 74 65 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69  tep()] results i
1c9b0 6e 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f  n fewer than N o
1c9c0 70 63 6f 64 65 73 0a 2a 2a 20 20 20 20 20 20 20  pcodes.**       
1c9d0 20 20 20 62 65 69 6e 67 20 65 78 65 63 75 74 65     being execute
1c9e0 64 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67  d, then the prog
1c9f0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73  ress callback is
1ca00 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a   never invoked..
1ca10 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45  **.** {H12916} E
1ca20 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71  very call to [sq
1ca30 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1ca40 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20  andler()].**    
1ca50 20 20 20 20 20 20 6f 76 65 72 77 72 69 74 65 73        overwrites
1ca60 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
1ca70 72 65 67 69 73 74 65 72 65 64 20 70 72 6f 67 72  registered progr
1ca80 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  ess handler..**.
1ca90 2a 2a 20 7b 48 31 32 39 31 37 7d 20 49 66 20 74  ** {H12917} If t
1caa0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1cab0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
1cac0 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f  NULL then no pro
1cad0 67 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20  gress.**        
1cae0 20 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76    handler is inv
1caf0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  oked..**.** {H12
1cb00 39 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67  918} If the prog
1cb10 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
1cb20 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f  turns a result o
1cb30 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65  ther than 0, the
1cb40 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
1cb50 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 61 20  e behavior is a 
1cb60 69 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  if [sqlite3_inte
1cb70 72 72 75 70 74 28 29 5d 20 68 61 64 20 62 65 65  rrupt()] had bee
1cb80 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20  n called..**    
1cb90 20 20 20 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a        <S30500>.*
1cba0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
1cbb0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1cbc0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
1cbd0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
1cbe0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1cbf0 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
1cc00 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
1cc10 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30  nnection {H12700
1cc20 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S40200>.**.**
1cc30 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1cc40 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
1cc50 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f  atabase file who
1cc60 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e  se name is given
1cc70 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   by the.** filen
1cc80 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68  ame argument. Th
1cc90 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1cca0 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
1ccb0 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a  ed as UTF-8 for.
1ccc0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1ccd0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1cce0 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55  en_v2() and as U
1ccf0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
1cd00 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65  ive byte.** orde
1cd10 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  r for sqlite3_op
1cd20 65 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62  en16(). A [datab
1cd30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1cd40 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
1cd50 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
1cd60 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
1cd70 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
1cd80 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
1cd90 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
1cda0 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
1cdb0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1cdc0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1cdd0 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1cde0 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
1cdf0 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
1ce00 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
1ce10 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
1ce20 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
1ce30 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68  ** object. If th
1ce40 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1ce50 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
1ce60 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
1ce70 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
1ce80 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1ce90 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
1cea0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1ceb0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
1cec0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
1ced0 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
1cee0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
1cef0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
1cf00 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
1cf10 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
1cf20 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
1cf30 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a  n of the error..
1cf40 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
1cf50 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
1cf60 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
1cf70 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
1cf80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1cf90 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1cfa0 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
1cfb0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
1cfc0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1cfd0 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
1cfe0 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
1cff0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
1d000 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
1d010 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
1d020 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
1d030 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
1d040 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1d050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d060 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
1d070 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
1d080 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
1d090 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1d0a0 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
1d0b0 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
1d0c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1d0d0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
1d0e0 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
1d0f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
1d100 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
1d110 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
1d120 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
1d130 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
1d140 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
1d150 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
1d160 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
1d170 20 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   The flags param
1d180 65 74 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e  eter can take on
1d190 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
1d1a0 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
1d1b0 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
1d1c0 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
1d1d0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
1d1e0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53  N_NOMUTEX] or [S
1d1f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1d200 55 54 45 58 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a  UTEX] flags:.**.
1d210 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b  ** <dl>.** <dt>[
1d220 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1d230 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
1d240 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1d250 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
1d260 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
1d270 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1d280 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
1d290 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
1d2a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1d2b0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51  d>.**.** <dt>[SQ
1d2c0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1d2d0 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
1d2e0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1d2f0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1d300 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
1d310 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
1d320 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
1d330 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
1d340 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1d350 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1d360 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
1d370 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
1d380 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
1d390 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
1d3a0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
1d3b0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1d3c0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49  .**.** <dt>[SQLI
1d3d0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1d3e0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
1d3f0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
1d400 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1d410 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1d420 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1d430 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
1d440 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74  ates it if.** it
1d450 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
1d460 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
1d470 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
1d480 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
1d490 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
1d4a0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1d4b0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
1d4c0 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  d>.** </dl>.**.*
1d4d0 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
1d4e0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1d4f0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
1d500 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
1d510 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
1d520 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65  own above or one
1d530 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74   of the combinat
1d540 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1d550 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74   combined.** wit
1d560 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
1d570 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b  EN_NOMUTEX] or [
1d580 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1d590 4d 55 54 45 58 5d 20 66 6c 61 67 73 2c 0a 2a 2a  MUTEX] flags,.**
1d5a0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1d5b0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1d5c0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53  .**.** If the [S
1d5d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1d5e0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
1d5f0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1d600 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1d610 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
1d620 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
1d630 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
1d640 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
1d650 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
1d660 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
1d670 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
1d680 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
1d690 20 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    If the.** [SQL
1d6a0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
1d6b0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
1d6c0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1d6d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
1d6e0 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
1d6f0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
1d700 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
1d710 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
1d720 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
1d730 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
1d740 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1d750 74 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  t-time..**.** If
1d760 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1d770 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
1d780 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1d790 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
1d7a0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
1d7b0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
1d7c0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69  connection.  Thi
1d7d0 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
1d7e0 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
1d7f0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
1d800 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d810 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
1d820 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
1d830 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
1d840 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
1d850 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
1d860 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
1d870 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
1d880 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
1d890 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
1d8a0 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
1d8b0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
1d8c0 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
1d8d0 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
1d8e0 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
1d8f0 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
1d900 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
1d910 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
1d920 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
1d930 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
1d940 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e  .** If the filen
1d950 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
1d960 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
1d970 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
1d980 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
1d990 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
1d9a0 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69  eated.  This pri
1d9b0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
1d9c0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
1d9d0 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
1d9e0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
1d9f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1da00 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
1da10 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
1da20 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1da30 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1da40 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
1da50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
1da60 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
1da70 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ines the operati
1da80 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
1da90 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ace that.** the 
1daa0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
1dab0 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  nection should u
1dac0 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72  se.  If the four
1dad0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
1dae0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1daf0 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
1db00 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1db10 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
1db20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
1db30 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
1db40 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
1db50 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
1db60 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1db70 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
1db80 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1db90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
1dba0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
1dbb0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
1dbc0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
1dbd0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
1dbe0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
1dbf0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
1dc00 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
1dc10 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
1dc20 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
1dc30 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
1dc40 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
1dc50 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
1dc60 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
1dc70 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
1dc80 2a 2a 20 7b 48 31 32 37 30 31 7d 20 54 68 65 20  ** {H12701} The 
1dc90 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1dca0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1dcb0 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20  6()], and.**    
1dcc0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
1dcd0 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
1dce0 61 63 65 73 20 63 72 65 61 74 65 20 61 20 6e 65  aces create a ne
1dcf0 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  w.**          [d
1dd00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1dd10 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  on] associated w
1dd20 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
1dd30 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
1dd40 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72  e given in their
1dd50 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1dd60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 32 7d  ..**.** {H12702}
1dd70 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   The filename ar
1dd80 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
1dd90 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a  reted as UTF-8.*
1dda0 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b  *          for [
1ddb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
1ddc0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
1ddd0 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55  n_v2()] and as U
1dde0 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20  TF-16.**        
1ddf0 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20    in the native 
1de00 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b  byte order for [
1de10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1de20 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 33  ]..**.** {H12703
1de30 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
1de40 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
1de50 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1de60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1de70 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ],.**          o
1de80 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
1de90 76 32 28 29 5d 20 77 72 69 74 65 73 20 61 20 70  v2()] writes a p
1dea0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a  ointer to a new.
1deb0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
1dec0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ded0 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a  ] into *ppDb..**
1dee0 0a 2a 2a 20 7b 48 31 32 37 30 34 7d 20 54 68 65  .** {H12704} The
1def0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1df00 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1df10 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20  16()], and.**   
1df20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1df30 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
1df40 66 61 63 65 73 20 72 65 74 75 72 6e 20 5b 53 51  faces return [SQ
1df50 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75  LITE_OK] upon su
1df60 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20  ccess,.**       
1df70 20 20 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72     or an appropr
1df80 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
1df90 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  ] on failure..**
1dfa0 0a 2a 2a 20 7b 48 31 32 37 30 36 7d 20 54 68 65  .** {H12706} The
1dfb0 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e   default text en
1dfc0 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77  coding for a new
1dfd0 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65   database create
1dfe0 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
1dff0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1e000 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  n()] or [sqlite3
1e010 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c  _open_v2()] will
1e020 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a   be UTF-8..**.**
1e030 20 7b 48 31 32 37 30 37 7d 20 54 68 65 20 64 65   {H12707} The de
1e040 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64  fault text encod
1e050 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61  ing for a new da
1e060 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75  tabase created u
1e070 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
1e080 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1e090 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ()] will be UTF-
1e0a0 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30  16..**.** {H1270
1e0b0 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
1e0c0 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72  open(F,D)] inter
1e0d0 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65  face is equivale
1e0e0 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  nt to.**        
1e0f0 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f    [sqlite3_open_
1e100 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65  v2(F,D,G,0)] whe
1e110 72 65 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  re the G paramet
1e120 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  er is.**        
1e130 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52    [SQLITE_OPEN_R
1e140 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54  EADWRITE]|[SQLIT
1e150 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a  E_OPEN_CREATE]..
1e160 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 31 7d 20 49  **.** {H12711} I
1e170 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
1e180 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
1e190 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
1e1a0 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
1e1b0 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
1e1c0 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
1e1d0 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74  READONLY] then t
1e1e0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1e1f0 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  pened.**        
1e200 20 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e    for reading on
1e210 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31  ly..**.** {H1271
1e220 32 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61  2} If the G para
1e230 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
1e240 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1e250 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  V)] contains the
1e260 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74  .**          bit
1e270 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
1e280 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 74  PEN_READWRITE] t
1e290 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1e2a0 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20   is opened.**   
1e2b0 20 20 20 20 20 20 20 72 65 61 64 69 6e 67 20 61         reading a
1e2c0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
1e2d0 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72  ssible, or for r
1e2e0 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74  eading only if t
1e2f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  he.**          f
1e300 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
1e310 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
1e320 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a  erating system..
1e330 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 33 7d 20 49  **.** {H12713} I
1e340 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
1e350 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
1e360 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
1e370 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  omits the.**    
1e380 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
1e390 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
1e3a0 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74  ATE] and the dat
1e3b0 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
1e3c0 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69  *          previ
1e3d0 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20  ously exist, an 
1e3e0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1e3f0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 34  d..**.** {H12714
1e400 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1e410 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1e420 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
1e430 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  )] contains the.
1e440 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
1e450 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
1e460 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74  EN_CREATE] and t
1e470 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1e480 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
1e490 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73   previously exis
1e4a0 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d  t, then an attem
1e4b0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 63 72  pt is made to cr
1e4c0 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  eate and.**     
1e4d0 20 20 20 20 20 69 6e 69 74 69 61 6c 69 7a 65 20       initialize 
1e4e0 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a  the database..**
1e4f0 0a 2a 2a 20 7b 48 31 32 37 31 37 7d 20 49 66 20  .** {H12717} If 
1e500 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1e510 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
1e520 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1e530 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a  te3_open16()],.*
1e540 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
1e550 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1e560 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  ] is ":memory:",
1e570 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65   then an private
1e580 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70  ,.**          ep
1e590 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f  hemeral, in-memo
1e5a0 72 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63  ry database is c
1e5b0 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
1e5c0 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20  onnection..**   
1e5d0 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20         <todo>Is 
1e5e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1e5f0 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  TE|SQLITE_OPEN_R
1e600 45 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65  EADWRITE require
1e610 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  d.**          in
1e620 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1e630 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  ()?</todo>.**.**
1e640 20 7b 48 31 32 37 31 39 7d 20 49 66 20 74 68 65   {H12719} If the
1e650 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c   filename is NUL
1e660 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
1e670 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
1e680 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20  vate,.**        
1e690 20 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64    ephemeral on-d
1e6a0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1e6b0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a  l be created..**
1e6c0 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
1e6d0 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  Is SQLITE_OPEN_C
1e6e0 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45  REATE|SQLITE_OPE
1e6f0 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75  N_READWRITE requ
1e700 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ired.**         
1e710 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
1e720 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  _v2()?</todo>.**
1e730 0a 2a 2a 20 7b 48 31 32 37 32 31 7d 20 54 68 65  .** {H12721} The
1e740 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1e750 63 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62  ction] created b
1e760 79 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  y [sqlite3_open_
1e770 76 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20  v2(F,D,G,V)].** 
1e780 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 75 73           will us
1e790 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  e the [sqlite3_v
1e7a0 66 73 5d 20 6f 62 6a 65 63 74 20 69 64 65 6e 74  fs] object ident
1e7b0 69 66 69 65 64 20 62 79 20 74 68 65 20 56 20 70  ified by the V p
1e7c0 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20 20 20  arameter,.**    
1e7d0 20 20 20 20 20 20 6f 72 20 74 68 65 20 64 65 66        or the def
1e7e0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1e7f0 73 5d 20 6f 62 6a 65 63 74 20 69 66 20 56 20 69  s] object if V i
1e800 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1e810 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 33 7d  ..**.** {H12723}
1e820 20 54 77 6f 20 5b 64 61 74 61 62 61 73 65 20 63   Two [database c
1e830 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c  onnections] will
1e840 20 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20   share a common 
1e850 63 61 63 68 65 20 69 66 20 62 6f 74 68 20 77 65  cache if both we
1e860 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  re.**          o
1e870 70 65 6e 65 64 20 77 69 74 68 20 74 68 65 20 73  pened with the s
1e880 61 6d 65 20 56 46 53 20 77 68 69 6c 65 20 5b 73  ame VFS while [s
1e890 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1e8a0 5d 20 77 61 73 20 65 6e 61 62 6c 65 64 20 61 6e  ] was enabled an
1e8b0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66  d.**          if
1e8c0 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65 73 20   both filenames 
1e8d0 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 75 73  compare equal us
1e8e0 69 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61 66 74  ing memcmp() aft
1e8f0 65 72 20 68 61 76 69 6e 67 20 62 65 65 6e 0a 2a  er having been.*
1e900 2a 20 20 20 20 20 20 20 20 20 20 70 72 6f 63 65  *          proce
1e910 73 73 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ssed by the [sql
1e920 69 74 65 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c  ite3_vfs | xFull
1e930 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64  Pathname] method
1e940 20 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a 2f 0a   of the VFS..*/.
1e950 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1e960 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1e970 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1e980 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1e990 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1e9a0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1e9b0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1e9c0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1e9d0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1e9e0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
1e9f0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
1ea00 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1ea10 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
1ea20 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1ea30 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1ea40 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1ea50 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1ea60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ea70 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1ea80 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1ea90 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1eaa0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1eab0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
1eac0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1ead0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1eae0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
1eaf0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
1eb00 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
1eb10 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
1eb20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
1eb30 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
1eb40 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1eb50 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
1eb60 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b  s And Messages {
1eb70 48 31 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e  H12800} <S60200>
1eb80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1eb90 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
1eba0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
1ebb0 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
1ebc0 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
1ebd0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1ebe0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
1ebf0 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
1ec00 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
1ec10 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
1ec20 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
1ec30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1ec40 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
1ec50 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
1ec60 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1ec70 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
1ec80 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
1ec90 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
1eca0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1ecb0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
1ecc0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
1ecd0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
1ece0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
1ecf0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
1ed00 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
1ed10 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
1ed20 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1ed30 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
1ed40 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1ed50 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
1ed60 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bled..**.** The 
1ed70 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1ed80 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
1ed90 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
1eda0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
1edb0 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
1edc0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
1edd0 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
1ede0 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
1edf0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d  ectively..** Mem
1ee00 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1ee10 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
1ee20 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
1ee30 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
1ee40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1ee50 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
1ee60 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
1ee70 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
1ee80 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
1ee90 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
1eea0 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
1eeb0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
1eec0 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
1eed0 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
1eee0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
1eef0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  e functions..**.
1ef00 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
1ef10 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
1ef20 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
1ef30 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
1ef40 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
1ef50 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
1ef60 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
1ef70 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
1ef80 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
1ef90 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
1efa0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
1efb0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
1efc0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
1efd0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
1efe0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
1eff0 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
1f000 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
1f010 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
1f020 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
1f030 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
1f040 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
1f050 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
1f060 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
1f070 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
1f080 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f090 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
1f0a0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
1f0b0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
1f0c0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
1f0d0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
1f0e0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
1f0f0 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
1f100 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
1f110 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
1f120 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
1f130 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
1f140 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
1f150 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
1f160 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
1f170 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
1f180 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
1f190 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
1f1a0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
1f1b0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
1f1c0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
1f1d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1f1e0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
1f1f0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
1f200 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
1f210 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
1f220 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  set..**.** INVAR
1f230 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1f240 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2801} The [sqlit
1f250 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69  e3_errcode(D)] i
1f260 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1f270 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20   the numeric.** 
1f280 20 20 20 20 20 20 20 20 20 5b 72 65 73 75 6c 74           [result
1f290 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
1f2a0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
1f2b0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
1f2c0 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  cently.**       
1f2d0 20 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66     failed interf
1f2e0 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61  ace call associa
1f2f0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
1f300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f310 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  n] D..**.** {H12
1f320 38 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  802} The [sqlite
1f330 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1f340 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65  de(D)] interface
1f350 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1f360 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  eric.**         
1f370 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1f380 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
1f390 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a  most recently.**
1f3a0 20 20 20 20 20 20 20 20 20 20 66 61 69 6c 65 64            failed
1f3b0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
1f3c0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1f3d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1f3e0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
1f3f0 2a 2a 20 7b 48 31 32 38 30 33 7d 20 54 68 65 20  ** {H12803} The 
1f400 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1f410 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  D)] and [sqlite3
1f420 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a  _errmsg16(D)].**
1f430 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
1f440 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67 6c  aces return Engl
1f450 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
1f460 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
1f470 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1f480 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f   error in the mo
1f490 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 61  stly recently fa
1f4a0 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63  iled interface c
1f4b0 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  all,.**         
1f4c0 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74 68   encoded as eith
1f4d0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1f4e0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1f4f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20  .**.** {H12807} 
1f500 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
1f510 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1f520 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b  _errmsg()] and [
1f530 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1f540 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
1f550 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
1f560 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20  the next SQLite 
1f570 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a  interface call..
1f580 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43  **.** {H12808} C
1f590 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74  alls to API rout
1f5a0 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  ines that do not
1f5b0 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
1f5c0 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
1f5d0 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c    (example: [sql
1f5e0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
1f5f0 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20  )]) do not.**   
1f600 20 20 20 20 20 20 20 63 68 61 6e 67 65 20 74 68         change th
1f610 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20  e error code or 
1f620 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e 65 64  message returned
1f630 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
1f640 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1f650 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 78  ()], [sqlite3_ex
1f660 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
1f670 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
1f680 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1f690 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  ], or [sqlite3_e
1f6a0 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  rrmsg16()]..**.*
1f6b0 2a 20 7b 48 31 32 38 30 39 7d 20 49 6e 74 65 72  * {H12809} Inter
1f6c0 66 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e  faces that are n
1f6d0 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ot associated wi
1f6e0 74 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  th a specific.**
1f6f0 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
1f700 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1f710 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20  (examples:.**   
1f720 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1f730 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73  mprintf()] or [s
1f740 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1f750 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a  ared_cache()].**
1f760 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74            do not
1f770 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
1f780 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
1f790 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1f7a0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20  te3_errcode()], 
1f7b0 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
1f7c0 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a  d_errcode()],.**
1f7d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1f7e0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72  e3_errmsg()], or
1f7f0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1f800 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
1f810 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
1f820 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20  lite3 *db);.int 
1f830 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1f840 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
1f850 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
1f860 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
1f870 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
1f880 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
1f890 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
1f8a0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1f8b0 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
1f8c0 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30  ent Object {H130
1f8d0 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20  00} <H13010>.** 
1f8e0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
1f8f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
1f900 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f910 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
1f920 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
1f930 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
1f940 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
1f950 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73  atement..** This
1f960 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f   object is vario
1f970 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20  usly known as a 
1f980 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  "prepared statem
1f990 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f  ent" or a.** "co
1f9a0 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65  mpiled SQL state
1f9b0 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20  ment" or simply 
1f9c0 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22  as a "statement"
1f9d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65  ..**.** The life
1f9e0 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20   of a statement 
1f9f0 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65  object goes some
1fa00 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a  thing like this:
1fa10 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
1fa20 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f  li> Create the o
1fa30 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
1fa40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1fa50 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a  )] or a related.
1fa60 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e  **      function
1fa70 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
1fa80 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70  alues to [host p
1fa90 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
1faa0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1fab0 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
1fac0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
1fad0 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
1fae0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1faf0 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
1fb00 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1fb10 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73  <li> Reset the s
1fb20 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
1fb30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1fb40 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
1fb50 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
1fb60 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
1fb70 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
1fb80 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
1fb90 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
1fba0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1fbb0 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  ()]..** </ol>.**
1fbc0 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63  .** Refer to doc
1fbd0 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e  umentation on in
1fbe0 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73  dividual methods
1fbf0 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74   above for addit
1fc00 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1fc10 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
1fc20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1fc30 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
1fc40 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
1fc50 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d  EF: Run-time Lim
1fc60 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32  its {H12760} <S2
1fc70 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0600>.**.** This
1fc80 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1fc90 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61  s the size of va
1fca0 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73  rious constructs
1fcb0 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a   to be limited.*
1fcc0 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f  * on a connectio
1fcd0 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  n by connection 
1fce0 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73  basis.  The firs
1fcf0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
1fd00 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
1fd10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73  connection] whos
1fd20 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65  e limit is to be
1fd30 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e   set or queried.
1fd40 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1fd50 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65  parameter is one
1fd60 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63   of the [limit c
1fd70 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20  ategories] that 
1fd80 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73  define a.** clas
1fd90 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20  s of constructs 
1fda0 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74  to be size limit
1fdb0 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70  ed.  The third p
1fdc0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1fdd0 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72  ** new limit for
1fde0 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e   that construct.
1fdf0 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72    The function r
1fe00 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c  eturns the old l
1fe10 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  imit..**.** If t
1fe20 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
1fe30 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
1fe40 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
1fe50 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f  unchanged..** Fo
1fe60 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65  r the limit cate
1fe70 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c  gory of SQLITE_L
1fe80 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69  IMIT_XYZ there i
1fe90 73 20 61 20 68 61 72 64 20 75 70 70 65 72 0a 2a  s a hard upper.*
1fea0 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20 61  * bound set by a
1feb0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20   compile-time C 
1fec0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1fed0 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f  ro named SQLITE_
1fee0 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65  MAX_XYZ..** (The
1fef0 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
1ff00 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
1ff10 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a  d to "_MAX_".).*
1ff20 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e  * Attempts to in
1ff30 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
1ff40 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
1ff50 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
1ff60 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
1ff70 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
1ff80 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a  upper limit..**.
1ff90 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69  ** Run time limi
1ffa0 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
1ffb0 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
1ffc0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
1ffd0 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
1ffe0 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
1fff0 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
20000 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
20010 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
20020 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
20030 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
20040 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
20050 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
20060 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65  e a.** webbrowse
20070 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
20080 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
20090 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
200a0 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
200b0 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
200c0 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
200d0 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
200e0 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
200f0 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
20100 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
20110 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
20120 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
20130 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
20140 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
20150 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
20160 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
20170 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
20180 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
20190 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
201a0 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
201b0 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
201c0 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
201d0 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
201e0 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
201f0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
20200 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
20210 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
20220 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
20230 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
20240 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
20250 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
20260 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
20270 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
20280 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
20290 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
202a0 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
202b0 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
202c0 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
202d0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
202e0 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
202f0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
20300 2a 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20 41 20  *.** {H12762} A 
20310 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
20320 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  to [sqlite3_limi
20330 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20  t(D,C,V)] where 
20340 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  V is.**         
20350 20 70 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65   positive change
20360 73 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74  s the limit on t
20370 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74  he size of const
20380 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a  ruct C in the.**
20390 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
203a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
203b0 44 20 74 6f 20 74 68 65 20 6c 65 73 73 65 72 20  D to the lesser 
203c0 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68 61 72  of V and the har
203d0 64 20 75 70 70 65 72 0a 2a 2a 20 20 20 20 20 20  d upper.**      
203e0 20 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65      bound on the
203f0 20 73 69 7a 65 20 6f 66 20 43 20 74 68 61 74 20   size of C that 
20400 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  is set at compil
20410 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e-time..**.** {H
20420 31 32 37 36 36 7d 20 41 20 73 75 63 63 65 73 73  12766} A success
20430 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
20440 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56  ite3_limit(D,C,V
20450 29 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e 65  )] where V is ne
20460 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
20470 20 20 20 6c 65 61 76 65 73 20 74 68 65 20 73 74     leaves the st
20480 61 74 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ate of the [data
20490 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
204a0 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a   D unchanged..**
204b0 0a 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41 20 73  .** {H12769} A s
204c0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
204d0 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  o [sqlite3_limit
204e0 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73  (D,C,V)] returns
204f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
20500 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
20510 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20  mit on the size 
20520 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69  of construct C i
20530 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
20540 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
20550 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20  ection] D as it 
20560 77 61 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65  was prior to the
20570 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   call..*/.int sq
20580 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
20590 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
205a0 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
205b0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
205c0 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
205d0 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c  ories {H12790} <
205e0 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f  H12760>.** KEYWO
205f0 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
20600 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74  gory} {limit cat
20610 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
20620 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
20630 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 61 73  efine various as
20640 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61 74 61  pects of a [data
20650 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
20660 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
20670 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a 65 20  limited in size 
20680 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  by calls to [sql
20690 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
206a0 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  * The meanings o
206b0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
206c0 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f 6c 6c  mits are as foll
206d0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ows:.**.** <dl>.
206e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
206f0 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
20700 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
20710 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
20720 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
20730 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a   table row.<dd>.
20740 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
20750 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
20760 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
20770 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
20780 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
20790 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
207a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
207b0 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
207c0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
207d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
207e0 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
207f0 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
20800 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
20810 20 6f 66 20 61 20 53 45 4c 45 43 54 20 6f 72 20   of a SELECT or 
20820 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
20830 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
20840 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
20850 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
20860 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
20870 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
20880 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
20890 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
208a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
208b0 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
208c0 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
208d0 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
208e0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
208f0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
20900 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
20910 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20920 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
20930 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
20940 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
20950 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
20960 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
20970 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
20980 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
20990 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
209a0 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
209b0 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
209c0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
209d0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
209e0 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
209f0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
20a00 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
20a10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20a20 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
20a30 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
20a40 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
20a50 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
20a60 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
20a70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20a80 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
20a90 6f 66 20 61 74 74 61 63 68 65 64 20 64 61 74 61  of attached data
20aa0 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bases.</dd>.**.*
20ab0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
20ac0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
20ad0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
20ae0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
20af0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
20b00 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
20b10 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20   the LIKE or.** 
20b20 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c  GLOB operators.<
20b30 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
20b40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
20b50 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
20b60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
20b70 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61  mum number of va
20b80 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51  riables in an SQ
20b90 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
20ba0 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64   can.** be bound
20bb0 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  .</dd>.** </dl>.
20bc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20bd0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
20be0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20bf0 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
20c00 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
20c10 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
20c20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
20c30 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
20c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20c50 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
20c60 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
20c70 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
20c80 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
20c90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
20ca0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
20cb0 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
20cc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
20cd0 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
20ce0 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
20cf0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
20d00 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
20d10 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
20d20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
20d30 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
20d40 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
20d50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
20d60 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
20d70 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
20d80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
20d90 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
20da0 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a             9../*
20db0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
20dc0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
20dd0 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30  tatement {H13010
20de0 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45  } <S10000>.** KE
20df0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
20e00 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
20e10 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
20e20 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
20e30 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
20e40 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
20e50 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
20e60 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
20e70 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
20e80 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
20e90 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
20ea0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
20eb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
20ec0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
20ed0 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b   prior call to [
20ee0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
20ef0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
20f00 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
20f10 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _open16()]..**.*
20f20 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
20f30 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
20f40 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
20f50 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
20f60 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
20f70 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
20f80 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
20f90 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
20fa0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
20fb0 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
20fc0 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
20fd0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
20fe0 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
20ff0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
21000 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
21010 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42  .**.** If the nB
21020 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
21030 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
21040 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
21050 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
21060 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
21070 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69  ator. If nByte i
21080 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
21090 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
210a0 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72  aximum.** number
210b0 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20   of  bytes read 
210c0 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e  from zSql.  When
210d0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
210e0 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a  gative, the.** z
210f0 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20  Sql string ends 
21100 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69  at either the fi
21110 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c  rst '\000' or '\
21120 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72  u0000' character
21130 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65   or.** the nByte
21140 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65  -th byte, whiche
21150 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
21160 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
21170 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  nows.** that the
21180 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
21190 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
211a0 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69  ed, then there i
211b0 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72  s a small.** per
211c0 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
211d0 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20  ge to be gained 
211e0 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  by passing an nB
211f0 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
21200 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74  at.** is equal t
21210 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  o the number of 
21220 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
21230 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
21240 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
21250 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
21260 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70   bytes..**.** *p
21270 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
21280 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
21290 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68  rst byte past th
212a0 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20  e end of the.** 
212b0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
212c0 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
212d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
212e0 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  y compile the fi
212f0 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  rst.** statement
21300 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
21310 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
21320 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65  nting to what re
21330 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69  mains.** uncompi
21340 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74  led..**.** *ppSt
21350 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
21360 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
21370 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
21380 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
21390 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
213a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
213b0 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65  ep()].  If there
213c0 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
213d0 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
213e0 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65  to NULL.  If the
213f0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
21400 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
21410 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
21420 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
21430 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
21440 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
21450 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41  t to NULL..** {A
21460 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69  13018} The calli
21470 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
21480 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
21490 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
214a0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
214b0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
214c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
214d0 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
214e0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
214f0 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73  .**.** On succes
21500 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  s, [SQLITE_OK] i
21510 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65  s returned, othe
21520 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
21530 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
21540 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
21550 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21560 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
21570 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
21580 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
21590 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
215a0 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
215b0 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
215c0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
215d0 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
215e0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
215f0 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
21600 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
21610 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22  ged..** In the "
21620 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
21630 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
21640 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
21650 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
21660 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
21670 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
21680 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
21690 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
216a0 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
216b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
216c0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
216d0 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69  o.** behave a di
216e0 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f  fferently in two
216f0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
21700 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20  >.** <li>.** If 
21710 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
21720 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
21730 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
21740 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
21750 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
21760 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
21770 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
21780 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
21790 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
217a0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
217b0 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
217c0 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68  it again.  If th
217d0 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61  e schema has cha
217e0 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79  nged in.** a way
217f0 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20   that makes the 
21800 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e  statement no lon
21810 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69  ger valid, [sqli
21820 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
21830 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e   still.** return
21840 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
21850 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68  .  But unlike th
21860 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
21870 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  r, [SQLITE_SCHEM
21880 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66  A] is.** now a f
21890 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c  atal error.  Cal
218a0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  ling [sqlite3_pr
218b0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69  epare_v2()] agai
218c0 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20  n will not make 
218d0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20  the.** error go 
218e0 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65  away.  Note: use
218f0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
21900 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ()] to find the 
21910 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70  text.** of the p
21920 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61  arsing error tha
21930 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20  t results in an 
21940 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
21950 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e  return..** </li>
21960 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57  .**.** <li>.** W
21970 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
21980 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
21990 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
219a0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
219b0 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
219c0 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
219d0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
219e0 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65  .  The legacy be
219f0 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
21a00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
21a10 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
21a20 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
21a30 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
21a40 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
21a50 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65  d you would have
21a60 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
21a70 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
21a80 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f  e3_reset()] in o
21a90 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20  rder.** to find 
21aa0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
21ab0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
21ac0 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
21ad0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
21ae0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
21af0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
21b00 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
21b10 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
21b20 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
21b30 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
21b40 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
21b50 20 7b 48 31 33 30 31 31 7d 20 54 68 65 20 5b 73   {H13011} The [s
21b60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64  qlite3_prepare(d
21b70 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64  b,zSql,...)] and
21b80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
21b90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21ba0 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69  (db,zSql,...)] i
21bb0 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70  nterfaces interp
21bc0 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ret the.**      
21bd0 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69      text in thei
21be0 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72  r zSql parameter
21bf0 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a   as UTF-8..**.**
21c00 20 7b 48 31 33 30 31 32 7d 20 54 68 65 20 5b 73   {H13012} The [s
21c10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
21c20 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61  (db,zSql,...)] a
21c30 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
21c40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
21c50 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e  6_v2(db,zSql,...
21c60 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e  )] interfaces in
21c70 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20  terpret the.**  
21c80 20 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20          text in 
21c90 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d  their zSql param
21ca0 65 74 65 72 20 61 73 20 55 54 46 2d 31 36 20 69  eter as UTF-16 i
21cb0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
21cc0 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  e order..**.** {
21cd0 48 31 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e  H13013} If the n
21ce0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  Byte argument to
21cf0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21d00 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  e_v2(db,zSql,nBy
21d10 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  te,...)].**     
21d20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72       and its var
21d30 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74 68  iants is less th
21d40 61 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c  an zero, the SQL
21d50 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20 20   text is.**     
21d60 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20 7a       read from z
21d70 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
21d80 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
21d90 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
21da0 2a 2a 20 7b 48 31 33 30 31 34 7d 20 49 66 20 74  ** {H13014} If t
21db0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
21dc0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
21dd0 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
21de0 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ,nByte,...)].** 
21df0 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73           and its
21e00 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e   variants is non
21e10 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
21e20 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20 62  at most nBytes b
21e30 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  ytes of.**      
21e40 20 20 20 20 53 51 4c 20 74 65 78 74 20 69 73 20      SQL text is 
21e50 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a  read from zSql..
21e60 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49  **.** {H13015} I
21e70 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
21e80 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c  re_v2(db,zSql,N,
21e90 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69  P,pzTail)] and i
21ea0 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20  ts variants.**  
21eb0 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20 7a          if the z
21ec0 53 71 6c 20 69 6e 70 75 74 20 74 65 78 74 20 63  Sql input text c
21ed0 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 68 61  ontains more tha
21ee0 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 65 6d  n one SQL statem
21ef0 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
21f00 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  and pzTail is no
21f10 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a  t NULL, then *pz
21f20 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
21f30 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20  point to the.** 
21f40 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20 62           first b
21f50 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64  yte past the end
21f60 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
21f70 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
21f80 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  Sql..**         
21f90 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73   <todo>What does
21fa0 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74   *pzTail point t
21fb0 6f 20 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e  o if there is on
21fc0 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f  e statement?</to
21fd0 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31  do>.**.** {H1301
21fe0 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  6} A successful 
21ff0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
22000 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
22010 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e  Sql,N,ppStmt,...
22020 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
22030 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
22040 69 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e 74  iants writes int
22050 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69 6e  o *ppStmt a poin
22060 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20  ter to a new.** 
22070 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
22080 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
22090 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55   a pointer to NU
220a0 4c 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61  LL if zSql conta
220b0 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ins.**          
220c0 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  nothing other th
220d0 61 6e 20 77 68 69 74 65 73 70 61 63 65 20 6f 72  an whitespace or
220e0 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a   comments..**.**
220f0 20 7b 48 31 33 30 31 39 7d 20 54 68 65 20 5b 73   {H13019} The [s
22100 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22110 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
22120 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  nd its variants 
22130 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
22140 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f     [SQLITE_OK] o
22150 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
22160 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
22170 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  on failure..**.*
22180 2a 20 7b 48 31 33 30 32 31 7d 20 42 65 66 6f 72  * {H13021} Befor
22190 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
221a0 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65  re(db,zSql,nByte
221b0 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d  ,ppStmt,pzTail)]
221c0 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 20 20   or its.**      
221d0 20 20 20 20 76 61 72 69 61 6e 74 73 20 72 65 74      variants ret
221e0 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 28 61  urns an error (a
221f0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
22200 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29  han [SQLITE_OK])
22210 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
22220 65 79 20 66 69 72 73 74 20 73 65 74 20 2a 70 70  ey first set *pp
22230 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  Stmt to NULL..*/
22240 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
22250 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
22260 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
22270 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
22280 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
22290 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
222a0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
222b0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
222c0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
222d0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
222e0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
222f0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
22300 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
22310 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
22320 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
22330 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
22340 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
22350 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
22360 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
22370 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
22380 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
22390 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
223a0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
223b0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
223c0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
223d0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
223e0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
223f0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
22400 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
22410 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
22420 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
22430 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
22440 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
22450 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
22460 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
22470 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
22480 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
22490 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
224a0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
224b0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
224c0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
224d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
224e0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
224f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
22500 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
22510 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
22520 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
22530 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
22540 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
22550 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
22560 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
22570 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
22580 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
22590 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
225a0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
225b0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
225c0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
225d0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
225e0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
225f0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
22600 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
22610 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
22620 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
22630 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
22640 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
22650 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
22660 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
22670 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
22680 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
22690 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
226a0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
226b0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
226c0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
226d0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
226e0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
226f0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
22700 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
22710 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
22720 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
22730 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
22740 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
22750 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
22760 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
22770 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
22780 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33  QL {H13100} <H13
22790 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  000>.**.** This 
227a0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
227b0 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
227c0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
227d0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
227e0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
227f0 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
22800 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22810 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
22820 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
22830 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
22840 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22850 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
22860 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
22870 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
22880 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
22890 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65  101} If the [pre
228a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
228b0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61   passed as the a
228c0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20  rgument to.**   
228d0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
228e0 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
228f0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
22900 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22910 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  e_v2()] or.**   
22920 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
22930 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
22940 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   then [sqlite3_s
22950 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a  ql()] returns.**
22960 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e            a poin
22970 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
22980 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20  rminated string 
22990 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46  containing a UTF
229a0 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20  -8 rendering.** 
229b0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
229c0 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61  original SQL sta
229d0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tement..**.** {H
229e0 31 33 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70  13102} If the [p
229f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22a00 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65  t] passed as the
22a10 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
22a20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
22a30 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
22a40 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
22a50 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
22a60 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  are()] or.**    
22a70 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
22a80 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65  repare16()], the
22a90 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  n [sqlite3_sql()
22aa0 5d 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ] returns a NULL
22ab0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
22ac0 7b 48 31 33 31 30 33 7d 20 54 68 65 20 73 74 72  {H13103} The str
22ad0 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
22ae0 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d  [sqlite3_sql(S)]
22af0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
22b00 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
22b10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22b20 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65  ent] S is delete
22b30 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
22b40 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a  _finalize(S)]..*
22b50 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
22b60 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
22b70 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
22b80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22b90 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
22ba0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20  ed Value Object 
22bb0 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30  {H15000} <S20200
22bc0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
22bd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
22be0 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
22bf0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
22c00 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
22c10 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
22c20 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
22c30 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
22c40 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
22c50 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
22c60 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
22c70 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
22c80 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
22c90 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
22ca0 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65  it stores. Value
22cb0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
22cc0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
22cd0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
22ce0 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
22cf0 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
22d00 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
22d10 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
22d20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
22d30 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
22d40 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
22d50 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
22d60 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
22d70 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
22d80 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
22d90 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
22da0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
22db0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
22dc0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
22dd0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
22de0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
22df0 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
22e00 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
22e10 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
22e20 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
22e30 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
22e40 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
22e50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
22e60 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
22e70 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
22e80 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
22e90 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
22ea0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
22eb0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
22ec0 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65   A internal mute
22ed0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
22ee0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
22ef0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
22f00 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
22f10 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
22f20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
22f30 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
22f40 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
22f50 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
22f60 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
22f70 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
22f80 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
22f90 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
22fa0 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
22fb0 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
22fc0 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
22fd0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
22fe0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
22ff0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
23000 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
23010 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
23020 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
23030 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
23040 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
23050 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
23060 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
23070 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
23080 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
23090 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
230a0 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
230b0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
230c0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
230d0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
230e0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
230f0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
23100 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
23110 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
23120 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72  tween between pr
23130 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
23140 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
23150 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
23160 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
23170 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
23180 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23190 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
231a0 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
231b0 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
231c0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
231d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
231e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
231f0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
23200 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
23210 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
23220 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
23230 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
23240 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
23250 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
23260 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
23270 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
23280 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
23290 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
232a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
232b0 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
232c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
232d0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
232e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
232f0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
23300 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
23310 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
23320 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
23330 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
23340 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
23350 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
23360 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
23370 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23380 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
23390 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48  ontext Object {H
233a0 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a  16001} <S20200>.
233b0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
233c0 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
233d0 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
233e0 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
233f0 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
23400 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
23410 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
23420 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
23430 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
23440 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
23450 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
23460 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
23470 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
23480 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
23490 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
234a0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
234b0 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
234c0 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
234d0 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
234e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
234f0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
23500 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
23510 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
23520 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
23530 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
23540 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
23550 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
23560 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
23570 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
23580 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
23590 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
235a0 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
235b0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
235c0 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
235d0 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
235e0 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
235f0 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
23600 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31  d Statements {H1
23610 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3500} <S70300>.*
23620 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
23630 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
23640 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
23650 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
23660 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
23670 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
23680 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
23690 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
236a0 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  nding}.**.** In 
236b0 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20  the SQL strings 
236c0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
236d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
236e0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
236f0 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
23700 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
23710 20 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20   a parameter in 
23720 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66 6f 72  one of these for
23730 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ms:.**.** <ul>.*
23740 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
23750 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
23760 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
23770 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
23780 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
23790 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   In the paramete
237a0 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62  r forms shown ab
237b0 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e  ove NNN is an in
237c0 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
237d0 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61 6e 20  * and VVV is an 
237e0 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61  alpha-numeric pa
237f0 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 68  rameter name. Th
23800 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
23810 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
23820 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
23830 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
23840 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
23850 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
23860 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
23870 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
23880 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
23890 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  ed here..**.** T
238a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
238b0 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
238c0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
238d0 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
238e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
238f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
23900 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
23910 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
23920 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
23930 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
23940 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
23950 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
23960 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
23970 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
23980 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65  e set..** The le
23990 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
239a0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
239b0 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68  x of 1.  When th
239c0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
239d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
239e0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
239f0 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
23a00 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
23a10 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
23a20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
23a30 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
23a40 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69  rrence..** The i
23a50 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
23a60 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
23a70 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
23a80 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
23a90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
23aa0 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
23ab0 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e  desired.  The in
23ac0 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
23ad0 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
23ae0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
23af0 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c  ..** The NNN val
23b00 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
23b10 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
23b20 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
23b30 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
23b40 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
23b50 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
23b60 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
23b70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  .**.** The third
23b80 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
23b90 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
23ba0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
23bb0 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  .**.** In those 
23bc0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
23bd0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
23be0 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
23bf0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
23c00 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
23c10 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
23c20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
23c30 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
23c40 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
23c50 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
23c60 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
23c70 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
23c80 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
23c90 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
23ca0 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e  egative, the len
23cb0 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
23cc0 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
23cd0 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
23ce0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
23cf0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
23d00 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 67  ** The fifth arg
23d10 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
23d20 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
23d30 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
23d40 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
23d50 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
23d60 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
23d70 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
23d80 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
23d90 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
23da0 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
23db0 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 20 74  ed with it. If t
23dc0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
23dd0 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
23de0 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
23df0 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
23e00 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
23e10 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
23e20 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
23e30 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
23e40 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
23e50 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
23e60 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  ed..** If the fi
23e70 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
23e80 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
23e90 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
23ea0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
23eb0 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
23ec0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
23ed0 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
23ee0 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
23ef0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
23f00 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
23f10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23f20 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
23f30 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
23f40 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
23f50 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
23f60 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
23f70 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20  es.  A zeroblob 
23f80 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
23f90 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
23fa0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
23fb0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
23fc0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
23fd0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
23fe0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
23ff0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
24000 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
24010 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
24020 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
24030 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
24040 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
24050 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
24060 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
24070 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
24080 20 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75   A negative valu
24090 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
240a0 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
240b0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
240c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
240d0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
240e0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
240f0 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73  lled after.** [s
24100 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
24110 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61  2()] (and its va
24120 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69  riants) or [sqli
24130 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64  te3_reset()] and
24140 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69  .** before [sqli
24150 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
24160 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
24170 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
24180 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
24190 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e  ] routine..** Un
241a0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
241b0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
241c0 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
241d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
241e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
241f0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
24200 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66  an error code if
24210 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65  .** anything goe
24220 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54  s wrong.  [SQLIT
24230 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
24240 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
24250 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
24260 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
24270 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
24280 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
24290 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
242a0 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
242b0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
242c0 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75  ned if these rou
242d0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
242e0 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c   on a.** virtual
242f0 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73   machine that is
24300 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65   the wrong state
24310 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c   or which has al
24320 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c  ready been final
24330 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69  ized..** Detecti
24340 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20  on of misuse is 
24350 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70  unreliable.  App
24360 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
24370 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f   not depend.** o
24380 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  n SQLITE_MISUSE 
24390 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45  returns.  SQLITE
243a0 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e  _MISUSE is inten
243b0 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ded to indicate 
243c0 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72  a.** a logic err
243d0 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63  or in the applic
243e0 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76  ation.  Future v
243f0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
24400 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63  e might.** panic
24410 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74   rather than ret
24420 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
24430 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  E..**.** See als
24440 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
24450 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
24460 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
24470 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
24480 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
24490 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
244a0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
244b0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
244c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20  .**.** {H13506} 
244d0 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65  The [SQL stateme
244e0 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63  nt compiler] rec
244f0 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f  ognizes tokens o
24500 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20  f the forms.**  
24510 20 20 20 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e          "?", "?N
24520 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 3a 56  NN", "$VVV", ":V
24530 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56 22 20  VV", and "@VVV" 
24540 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  as SQL parameter
24550 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  s,.**          w
24560 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20  here NNN is any 
24570 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20  sequence of one 
24580 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a  or more digits.*
24590 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77  *          and w
245a0 68 65 72 65 20 56 56 56 20 69 73 20 61 6e 79 20  here VVV is any 
245b0 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20  sequence of one 
245c0 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d  or more alphanum
245d0 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  eric.**         
245e0 20 63 68 61 72 61 63 74 65 72 73 20 6f 72 20 22   characters or "
245f0 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66  ::" optionally f
24600 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 73 74 72  ollowed by a str
24610 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a  ing containing.*
24620 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 73 70  *          no sp
24630 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e  aces and contain
24640 65 64 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74  ed within parent
24650 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  heses..**.** {H1
24660 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61  3509} The initia
24670 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51  l value of an SQ
24680 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  L parameter is N
24690 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ULL..**.** {H135
246a0 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  12} The index of
246b0 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61   an "?" SQL para
246c0 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72  meter is one lar
246d0 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20  ger than the.** 
246e0 20 20 20 20 20 20 20 20 20 6c 61 72 67 65 73 74           largest
246f0 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61   index of SQL pa
24700 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c  rameter to the l
24710 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20  eft, or 1 if.** 
24720 20 20 20 20 20 20 20 20 20 74 68 65 20 22 3f 22           the "?"
24730 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74   is the leftmost
24740 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a   SQL parameter..
24750 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54  **.** {H13515} T
24760 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22  he index of an "
24770 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65  ?NNN" SQL parame
24780 74 65 72 20 69 73 20 74 68 65 20 69 6e 74 65 67  ter is the integ
24790 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  er NNN..**.** {H
247a0 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78  13518} The index
247b0 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22   of an ":VVV", "
247c0 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22  $VVV", or "@VVV"
247d0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
247e0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
247f0 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e  e same as the in
24800 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20  dex of leftmost 
24810 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20 74  occurrences of t
24820 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
24830 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20 6f      parameter, o
24840 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20  r one more than 
24850 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65  the largest inde
24860 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20  x over all.**   
24870 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
24880 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69 66  s to the left if
24890 20 74 68 69 73 20 69 73 20 74 68 65 20 66 69 72   this is the fir
248a0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a  st occurrence.**
248b0 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 69            of thi
248c0 73 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20  s parameter, or 
248d0 31 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65  1 if this is the
248e0 20 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 6d 65   leftmost parame
248f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ter..**.** {H135
24900 32 31 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61  21} The [SQL sta
24910 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d  tement compiler]
24920 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 5b   fails with an [
24930 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a  SQLITE_RANGE].**
24940 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20            error 
24950 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  if the index of 
24960 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
24970 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 0a   is less than 1.
24980 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 67  **          or g
24990 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
249a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c  compile-time SQL
249b0 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45  ITE_MAX_VARIABLE
249c0 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20  _NUMBER.**      
249d0 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a      parameter..*
249e0 2a 0a 2a 2a 20 7b 48 31 33 35 32 34 7d 20 43 61  *.** {H13524} Ca
249f0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
24a00 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69  bind_text | sqli
24a10 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e  te3_bind(S,N,V,.
24a20 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
24a30 20 61 73 73 6f 63 69 61 74 65 20 74 68 65 20 76   associate the v
24a40 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20  alue V with all 
24a50 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68  SQL parameters h
24a60 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20  aving an.**     
24a70 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20       index of N 
24a80 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
24a90 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
24aa0 2a 0a 2a 2a 20 7b 48 31 33 35 32 37 7d 20 43 61  *.** {H13527} Ca
24ab0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
24ac0 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69  bind_text | sqli
24ad0 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e  te3_bind(S,N,...
24ae0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
24af0 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 63 61  verride prior ca
24b00 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  lls with the sam
24b10 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e  e values of S an
24b20 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  d N..**.** {H135
24b30 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74  30} Bindings est
24b40 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c  ablished by [sql
24b50 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
24b60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c   sqlite3_bind(S,
24b70 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
24b80 20 20 70 65 72 73 69 73 74 20 61 63 72 6f 73 73    persist across
24b90 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
24ba0 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a  e3_reset(S)]..**
24bb0 0a 2a 2a 20 7b 48 31 33 35 33 33 7d 20 49 6e 20  .** {H13533} In 
24bc0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
24bd0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
24be0 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
24bf0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
24c00 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
24c10 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
24c20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
24c30 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
24c40 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64  ,D)] SQLite bind
24c50 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a  s the first L.**
24c60 20 20 20 20 20 20 20 20 20 20 62 79 74 65 73 20            bytes 
24c70 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
24c80 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
24c90 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a   by V, when L.**
24ca0 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e            is non
24cb0 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a  -negative..**.**
24cc0 20 7b 48 31 33 35 33 36 7d 20 49 6e 20 63 61 6c   {H13536} In cal
24cd0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
24ce0 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
24cf0 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ,D)] or.**      
24d00 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
24d10 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
24d20 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64  ,D)] SQLite bind
24d30 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20  s characters.** 
24d40 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20           from V 
24d50 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
24d60 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
24d70 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74   when L is negat
24d80 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ive..**.** {H135
24d90 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  39} In calls to 
24da0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
24db0 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a  ob(S,N,V,L,D)],.
24dc0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
24dd0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
24de0 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a  ,N,V,L,D)], or.*
24df0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
24e00 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
24e10 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e  S,N,V,L,D)] when
24e20 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61   D is the specia
24e30 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  l.**          co
24e40 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53  nstant [SQLITE_S
24e50 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61  TATIC], SQLite a
24e60 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
24e70 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20  value V.**      
24e80 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73      is held in s
24e90 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20  tatic unmanaged 
24ea0 73 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20  space that will 
24eb0 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20  not change.**   
24ec0 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 74 68         during th
24ed0 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68  e lifetime of th
24ee0 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e binding..**.**
24ef0 20 7b 48 31 33 35 34 32 7d 20 49 6e 20 63 61 6c   {H13542} In cal
24f00 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
24f10 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
24f20 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
24f30 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
24f40 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
24f50 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
24f60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
24f70 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
24f80 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20  ] when D is the 
24f90 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20  special.**      
24fa0 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51      constant [SQ
24fb0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
24fc0 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b   the routine mak
24fd0 65 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  es a.**         
24fe0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
24ff0 20 74 68 65 20 76 61 6c 75 65 20 56 20 62 65 66   the value V bef
25000 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
25010 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49  **.** {H13545} I
25020 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
25030 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
25040 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
25050 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
25060 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
25070 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
25080 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
25090 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
250a0 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73  ,L,D)] when D is
250b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
250c0 20 20 20 20 20 20 20 20 20 20 61 20 66 75 6e 63            a func
250d0 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76  tion, SQLite inv
250e0 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74 69  okes that functi
250f0 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68  on to destroy th
25100 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  e.**          va
25110 6c 75 65 20 56 20 61 66 74 65 72 20 69 74 20 68  lue V after it h
25120 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
25130 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a  g the value V..*
25140 2a 0a 2a 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e  *.** {H13548} In
25150 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
25160 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
25170 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76  (S,N,V,L)] the v
25180 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20  alue bound.**   
25190 20 20 20 20 20 20 20 69 73 20 61 20 42 4c 4f 42         is a BLOB
251a0 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20   of L bytes, or 
251b0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
251c0 4f 42 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74  OB if L is negat
251d0 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ive..**.** {H135
251e0 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  51} In calls to 
251f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
25200 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20  lue(S,N,V)] the 
25210 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a  V argument may.*
25220 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 65 69  *          be ei
25230 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65  ther a [protecte
25240 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
25250 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a   object or an.**
25260 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f            [unpro
25270 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
25280 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  alue] object..*/
25290 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
252a0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
252b0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
252c0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
252d0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
252e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
252f0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
25300 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
25310 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
25320 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
25330 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
25340 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
25350 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
25360 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
25370 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
25380 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
25390 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
253a0 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
253b0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
253c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
253d0 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
253e0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
253f0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
25400 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
25410 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25420 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
25430 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
25440 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
25450 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
25460 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25470 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
25480 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
25490 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
254a0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
254b0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
254c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
254d0 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
254e0 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33 36 30  arameters {H1360
254f0 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
25500 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
25510 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
25520 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
25530 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
25540 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
25550 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
25560 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
25570 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
25580 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
25590 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
255a0 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
255b0 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
255c0 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
255d0 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
255e0 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
255f0 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
25600 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
25610 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
25620 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ime..**.** This 
25630 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
25640 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
25650 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
25660 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
25670 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
25680 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
25690 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
256a0 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
256b0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
256c0 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
256d0 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
256e0 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72  s of the ?NNN ar
256f0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
25700 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
25710 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20  the list..**.** 
25720 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
25730 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
25740 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
25750 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
25760 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
25770 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
25780 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
25790 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
257a0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
257b0 2a 2a 20 7b 48 31 33 36 30 31 7d 20 54 68 65 20  ** {H13601} The 
257c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
257d0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53 29  rameter_count(S)
257e0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
257f0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
25800 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65  the largest inde
25810 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61 72  x of all SQL par
25820 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65 0a 2a  ameters in the.*
25830 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
25840 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25850 53 2c 20 6f 72 20 30 20 69 66 20 53 20 63 6f 6e  S, or 0 if S con
25860 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72  tains no SQL par
25870 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20  ameters..*/.int 
25880 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
25890 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
258a0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
258b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
258c0 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
258d0 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20  ameter {H13620} 
258e0 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70300>.**.** T
258f0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
25900 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
25910 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25920 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61   n-th.** [SQL pa
25930 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70  rameter] in a [p
25940 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25950 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  t]..** SQL param
25960 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
25970 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
25980 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
25990 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
259a0 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
259b0 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
259c0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
259d0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
259e0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
259f0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
25a00 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
25a10 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
25a20 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
25a30 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
25a40 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50  f the name..** P
25a50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
25a60 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
25a70 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
25a80 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
25a90 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c  me.** and are al
25aa0 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  so referred to a
25ab0 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  s "anonymous par
25ac0 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
25ad0 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
25ae0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
25af0 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
25b00 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
25b10 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f  value n is out o
25b20 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
25b30 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e n-th parameter
25b40 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
25b50 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
25b60 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74  turned.  The ret
25b70 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
25b80 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
25b90 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
25ba0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
25bb0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
25bc0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
25bd0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
25be0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25bf0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
25c00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
25c10 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
25c20 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
25c30 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
25c40 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
25c50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
25c60 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
25c70 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
25c80 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
25c90 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
25ca0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
25cb0 20 7b 48 31 33 36 32 31 7d 20 54 68 65 20 5b 73   {H13621} The [s
25cc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
25cd0 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d  meter_name(S,N)]
25ce0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25cf0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
25d00 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
25d10 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   of the name of 
25d20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
25d30 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  r in.**         
25d40 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25d50 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69  tatement] S havi
25d60 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a  ng index N, or.*
25d70 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  *          NULL 
25d80 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53  if there is no S
25d90 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74  QL parameter wit
25da0 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20  h index N or if 
25db0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
25dc0 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69  parameter with i
25dd0 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f  ndex N is an ano
25de0 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
25df0 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63   "?"..*/.const c
25e00 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
25e10 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
25e20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25e30 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
25e40 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
25e50 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
25e60 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48   A Given Name {H
25e70 31 33 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13640} <S70300>.
25e80 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65  **.** Return the
25e90 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
25ea0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
25eb0 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a   its name.  The.
25ec0 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
25ed0 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
25ee0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
25ef0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
25f00 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
25f10 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
25f20 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41  ite3_bind()].  A
25f30 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
25f40 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
25f50 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
25f60 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72   found.  The par
25f70 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
25f80 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
25f90 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
25fa0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
25fb0 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
25fc0 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
25fd0 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
25fe0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
25ff0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
26000 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
26010 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
26020 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
26030 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
26040 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
26050 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
26060 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
26070 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
26080 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
26090 7b 48 31 33 36 34 31 7d 20 54 68 65 20 5b 73 71  {H13641} The [sq
260a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
260b0 65 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d  eter_index(S,N)]
260c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
260d0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ns.**          t
260e0 68 65 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20  he index of SQL 
260f0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
26100 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26110 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
26120 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d    S whose name m
26130 61 74 63 68 65 73 20 74 68 65 20 55 54 46 2d 38  atches the UTF-8
26140 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20   string N, or 0 
26150 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20  if there is.**  
26160 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68          no match
26170 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
26180 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
26190 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
261a0 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
261b0 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
261c0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
261d0 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
261e0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
261f0 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53  ment {H13660} <S
26200 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e  70300>.**.** Con
26210 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
26220 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
26230 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
26240 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
26250 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
26260 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
26270 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
26280 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26290 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f  ..** Use this ro
262a0 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
262b0 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
262c0 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  rs to NULL..**.*
262d0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
262e0 0a 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54 68 65  .** {H13661} The
262f0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
26300 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74  bindings(S)] int
26310 65 72 66 61 63 65 20 72 65 73 65 74 73 20 61 6c  erface resets al
26320 6c 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20  l SQL.**        
26330 20 20 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64    parameter bind
26340 69 6e 67 73 20 69 6e 20 74 68 65 20 5b 70 72 65  ings in the [pre
26350 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26360 20 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e   S back to NULL.
26370 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
26380 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
26390 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
263a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
263b0 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
263c0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
263d0 74 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37  t {H13710} <S107
263e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  00>.**.** Return
263f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
26400 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
26410 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
26420 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
26430 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26440 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  . This routine r
26450 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
26460 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
26470 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
26480 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
26490 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
264a0 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
264b0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
264c0 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54  **.** {H13711} T
264d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
264e0 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74  mn_count(S)] int
264f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
26500 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
26510 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73           columns
26520 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
26530 65 74 20 67 65 6e 65 72 61 74 65 64 20 62 79 20  et generated by 
26540 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
26550 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20  atement] S,.**  
26560 20 20 20 20 20 20 20 20 6f 72 20 30 20 69 66 20          or 0 if 
26570 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72  S does not gener
26580 61 74 65 20 61 20 72 65 73 75 6c 74 20 73 65 74  ate a result set
26590 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
265a0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
265b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
265c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
265d0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
265e0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
265f0 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37  t {H13720} <S107
26600 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
26610 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
26620 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
26630 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
26640 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
26650 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
26660 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
26670 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  ement.  The sqli
26680 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
26690 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
266a0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
266b0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
266c0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
266d0 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
266e0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
266f0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
26700 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
26710 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
26720 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  16 string.  The 
26730 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
26740 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
26750 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
26760 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
26770 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
26780 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e  ement. The secon
26790 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
267a0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
267b0 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f  ber.  The leftmo
267c0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
267d0 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ber 0..**.** The
267e0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
267f0 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
26800 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
26810 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26820 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
26830 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
26840 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
26850 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
26860 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
26870 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26880 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
26890 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
268a0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
268b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74  ..**.** If sqlit
268c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
268d0 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
268e0 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
268f0 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
26900 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
26910 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
26920 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
26930 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
26940 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
26950 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
26960 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
26970 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
26980 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
26990 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
269a0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
269b0 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
269c0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
269d0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
269e0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
269f0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
26a00 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
26a10 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
26a20 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
26a30 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
26a40 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20  the next..**.** 
26a50 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
26a60 2a 20 7b 48 31 33 37 32 31 7d 20 41 20 73 75 63  * {H13721} A suc
26a70 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
26a80 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
26a90 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
26aa0 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
26ab0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
26ac0 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ns the name of t
26ad0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77  he Nth column (w
26ae0 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20  here 0 is.**    
26af0 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f        the leftmo
26b00 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74  st column) for t
26b10 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
26b20 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
26b30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26b40 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72  ment] S as a zer
26b50 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
26b60 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
26b70 20 7b 48 31 33 37 32 33 7d 20 41 20 73 75 63 63   {H13723} A succ
26b80 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
26b90 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
26ba0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
26bb0 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
26bc0 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75    interface retu
26bd0 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  rns the name of 
26be0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
26bf0 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20  where 0 is.**   
26c00 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d         the leftm
26c10 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20  ost column) for 
26c20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
26c30 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
26c40 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
26c50 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65  ement] S as a ze
26c60 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
26c70 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20  F-16 string.**  
26c80 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e          in the n
26c90 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
26ca0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d  ..**.** {H13724}
26cb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
26cc0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64  lumn_name()] and
26cd0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26ce0 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20  _name16()].**   
26cf0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
26d00 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20  s return a NULL 
26d10 70 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79 20  pointer if they 
26d20 61 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a  are unable to.**
26d30 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61            alloca
26d40 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
26d50 64 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72  d their normal r
26d60 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a  eturn strings..*
26d70 2a 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20 49 66  *.** {H13725} If
26d80 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
26d90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
26da0 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f  umn_name(S,N)] o
26db0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
26dc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
26dd0 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75  me16(S,N)] is ou
26de0 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e  t of range, then
26df0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
26e00 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
26e10 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  rn a NULL pointe
26e20 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36  r..**.** {H13726
26e30 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  } The strings re
26e40 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
26e50 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
26e60 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ,N)] and.**     
26e70 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
26e80 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  lumn_name16(S,N)
26e90 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  ] are valid unti
26ea0 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20  l the next.**   
26eb0 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65         call to e
26ec0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69  ither routine wi
26ed0 74 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e  th the same S an
26ee0 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  d N parameters.*
26ef0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e  *          or un
26f00 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  til [sqlite3_fin
26f10 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c  alize(S)] is cal
26f20 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  led..**.** {H137
26f30 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c  27} When a resul
26f40 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53  t column of a [S
26f50 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
26f60 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20   contains.**    
26f70 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75        an AS clau
26f80 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  se, the name of 
26f90 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  that column is t
26fa0 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a  he identifier.**
26fb0 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
26fc0 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 41 53   right of the AS
26fd0 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e   keyword..*/.con
26fe0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
26ff0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
27000 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
27010 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
27020 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
27030 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
27040 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
27050 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
27060 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
27070 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
27080 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e  H13740} <S10700>
27090 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
270a0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
270b0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
270c0 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f  ne what column o
270d0 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20  f what.** table 
270e0 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73  in which databas
270f0 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20  e a result of a 
27100 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
27110 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a  nt comes from..*
27120 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
27130 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
27140 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
27150 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
27160 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
27170 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
27180 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62  ing.  The _datab
27190 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
271a0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
271b0 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
271c0 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
271d0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
271e0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
271f0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
27200 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
27210 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68  lumn name..** Th
27220 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
27230 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
27240 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
27250 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
27260 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
27270 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
27280 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
27290 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
272a0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
272b0 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
272c0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
272d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
272e0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
272f0 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
27300 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
27310 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
27320 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
27330 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  mn..**.** The fi
27340 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
27350 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
27360 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  lls is a [prepar
27370 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
27380 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
27390 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
273a0 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
273b0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
273c0 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
273d0 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
273e0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
273f0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
27400 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74  .**.** If the Nt
27410 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
27420 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
27430 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
27440 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
27450 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
27460 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
27470 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
27480 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
27490 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65  .** NULL.  These
274a0 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
274b0 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
274c0 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
274d0 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
274e0 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69  occurs.  Otherwi
274f0 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
27500 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
27510 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
27520 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20  e, table.** and 
27530 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
27540 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
27550 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
27560 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74  om..**.** As wit
27570 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
27580 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70  te APIs, those p
27590 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31  ostfixed with "1
275a0 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
275b0 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
275c0 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66  ngs, the other f
275d0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
275e0 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  UTF-8. {END}.**.
275f0 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72  ** These APIs ar
27600 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
27610 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
27620 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
27630 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
27640 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
27650 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
27660 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64  ocessor symbol d
27670 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41  efined..**.** {A
27680 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f  13751}.** If two
27690 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
276a0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
276b0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
276c0 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
276d0 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
276e0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
276f0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
27700 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
27710 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
27720 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
27730 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
27740 2a 20 7b 48 31 33 37 34 31 7d 20 54 68 65 20 5b  * {H13741} The [
27750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
27760 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e  atabase_name(S,N
27770 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
27780 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
27790 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
277a0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
277b0 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  d name of the da
277c0 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63  tabase from whic
277d0 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  h the.**        
277e0 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
277f0 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70  umn of the [prep
27800 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27810 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a  S is extracted,.
27820 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e  **          or N
27830 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
27840 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20  olumn of S is a 
27850 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
27860 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
27870 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
27880 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
27890 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
278a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d  ..**.** {H13742}
278b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
278c0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
278d0 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  me16(S,N)] inter
278e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
278f0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
27900 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
27910 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72  e byte order zer
27920 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
27930 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
27940 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  e.**          fr
27950 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 68  om which the Nth
27960 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
27970 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
27980 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a  statement] S is.
27990 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 74 72  **          extr
279a0 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69  acted, or NULL i
279b0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
279c0 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72   of S is a gener
279d0 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  al expression.**
279e0 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
279f0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
27a00 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f  te memory to sto
27a10 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  re the name..**.
27a20 2a 2a 20 7b 48 31 33 37 34 33 7d 20 54 68 65 20  ** {H13743} The 
27a30 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
27a40 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d  table_name(S,N)]
27a50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
27a60 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
27a70 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
27a80 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
27a90 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
27aa0 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  e from which the
27ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
27ac0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
27ad0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
27ae0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20  statement] S is 
27af0 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20  extracted,.**   
27b00 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69         or NULL i
27b10 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
27b20 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72   of S is a gener
27b30 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  al expression.**
27b40 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
27b50 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
27b60 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f  te memory to sto
27b70 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  re the name..**.
27b80 2a 2a 20 7b 48 31 33 37 34 34 7d 20 54 68 65 20  ** {H13744} The 
27b90 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
27ba0 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e  table_name16(S,N
27bb0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
27bc0 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
27bd0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
27be0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
27bf0 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  rder zero-termin
27c00 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
27c10 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20   table.**       
27c20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68     from which th
27c30 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
27c40 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70  umn of the [prep
27c50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27c60 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  S is.**         
27c70 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
27c80 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
27c90 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20  olumn of S is a 
27ca0 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
27cb0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
27cc0 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
27cd0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
27ce0 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
27cf0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d  ..**.** {H13745}
27d00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
27d10 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
27d20 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
27d30 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
27d40 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
27d50 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
27d60 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
27d70 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66  e table column f
27d80 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a  rom which the.**
27d90 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
27da0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
27db0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
27dc0 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74  tement] S is ext
27dd0 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20  racted,.**      
27de0 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74      or NULL if t
27df0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
27e00 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
27e10 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
27e20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
27e30 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
27e40 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
27e50 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
27e60 7b 48 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71  {H13746} The [sq
27e70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
27e80 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  gin_name16(S,N)]
27e90 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
27ea0 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
27eb0 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
27ec0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
27ed0 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  er zero-terminat
27ee0 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
27ef0 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  able.**         
27f00 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69   column from whi
27f10 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ch the Nth resul
27f20 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  t column of the.
27f30 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
27f40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27f50 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c   S is extracted,
27f60 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
27f70 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20  Nth column.**   
27f80 20 20 20 20 20 20 20 6f 66 20 53 20 69 73 20 61         of S is a
27f90 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
27fa0 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65  ion or if unable
27fb0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
27fc0 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ory.**          
27fd0 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
27fe0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38  e..**.** {H13748
27ff0 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
28000 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  ues from.**     
28010 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
28020 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
28030 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
28040 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
28050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
28060 20 76 61 6c 69 64 20 66 6f 72 20 74 68 65 20 6c   valid for the l
28070 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b  ifetime of the [
28080 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28090 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nt].**          
280a0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63  or until the enc
280b0 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64  oding is changed
280c0 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61   by another meta
280d0 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  data.**         
280e0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
280f0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72 65  for the same pre
28100 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
28110 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
28120 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
28130 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20 49 66  *.** {A13751} If
28140 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
28150 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
28160 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   more.**        
28170 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
28180 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
28190 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
281a0 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
281b0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 68            for th
281c0 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
281d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
281e0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
281f0 20 20 20 20 20 20 20 20 20 20 61 74 20 74 68 65            at the
28200 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
28210 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
28220 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
28230 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
28240 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
28250 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
28260 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
28270 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
28280 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
28290 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
282a0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
282b0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
282c0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
282d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
282e0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
282f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28300 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
28310 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
28320 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
28330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
28340 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
28350 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
28360 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
28370 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
28380 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
28390 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
283a0 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
283b0 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
283c0 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31  Query Result {H1
283d0 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3760} <S10700>.*
283e0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
283f0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
28400 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28410 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
28420 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
28430 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
28440 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
28450 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
28460 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
28470 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
28480 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
28490 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
284a0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
284b0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
284c0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
284d0 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
284e0 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
284f0 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63  d.  If the Nth c
28500 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
28510 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
28520 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
28530 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
28540 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
28550 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65  returned..** The
28560 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
28570 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
28580 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a   encoded. {END}.
28590 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
285a0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
285b0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
285c0 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
285d0 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
285e0 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
285f0 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
28600 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
28610 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
28620 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
28630 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
28640 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
28650 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
28660 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
28670 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
28680 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
28690 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
286a0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
286b0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
286c0 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  (i==0)..**.** SQ
286d0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
286e0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
286f0 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61  g.  So just beca
28700 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
28710 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
28720 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
28730 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
28740 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
28750 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
28760 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
28770 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
28780 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
28790 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
287a0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
287b0 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
287c0 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65  ot static.  Type
287d0 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
287e0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
287f0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
28800 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
28810 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
28820 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
28830 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
28840 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d  :.**.** {H13761}
28850 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63    A successful c
28860 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
28870 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
28880 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 0a  S,N)] returns a.
28890 2a 2a 20 20 20 20 20 20 20 20 20 20 20 7a 65 72  **           zer
288a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
288b0 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  -8 string contai
288c0 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65  ning the declare
288d0 64 20 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 20  d datatype.**   
288e0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 74          of the t
288f0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
28900 20 61 70 70 65 61 72 73 20 61 73 20 74 68 65 20   appears as the 
28910 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62  Nth column (numb
28920 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ered.**         
28930 20 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65    from 0) of the
28940 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74   result set to t
28950 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
28960 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a  tement] S..**.**
28970 20 7b 48 31 33 37 36 32 7d 20 20 41 20 73 75 63   {H13762}  A suc
28980 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
28990 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
289a0 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d  decltype16(S,N)]
289b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
289c0 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72  turns a zero-ter
289d0 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e  minated UTF-16 n
289e0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
289f0 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20   string.**      
28a00 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20       containing 
28a10 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74  the declared dat
28a20 61 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62  atype of the tab
28a30 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61  le column that a
28a40 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20  ppears.**       
28a50 20 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63      as the Nth c
28a60 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20  olumn (numbered 
28a70 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72  from 0) of the r
28a80 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65  esult set to the
28a90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70  .**           [p
28aa0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28ab0 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  t] S..**.** {H13
28ac0 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65  763}  If N is le
28ad0 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69  ss than 0 or N i
28ae0 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f  s greater than o
28af0 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20  r equal to.**   
28b00 20 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62          the numb
28b10 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
28b20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
28b30 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20  tatement] S,.** 
28b40 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
28b50 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
28b60 66 20 53 20 69 73 20 61 6e 20 65 78 70 72 65 73  f S is an expres
28b70 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
28b80 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   rather.**      
28b90 20 20 20 20 20 74 68 61 6e 20 61 20 74 61 62 6c       than a tabl
28ba0 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20  e column, or if 
28bb0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
28bc0 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20  ion failure.**  
28bd0 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20           occurs 
28be0 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20  during encoding 
28bf0 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65  conversions, the
28c00 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63  n.**           c
28c10 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
28c20 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
28c30 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  (S,N)] or.**    
28c40 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
28c50 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
28c60 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e  6(S,N)] return N
28c70 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ULL..*/.const ch
28c80 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
28c90 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
28ca0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
28cb0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
28cc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
28cd0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
28ce0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
28cf0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
28d00 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
28d10 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53  ment {H13200} <S
28d20 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74  10000>.**.** Aft
28d30 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
28d40 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
28d50 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
28d60 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
28d70 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
28d80 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
28d90 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
28da0 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
28db0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
28dc0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
28dd0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
28de0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
28df0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
28e00 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
28e10 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
28e20 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
28e30 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
28e40 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
28e50 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
28e60 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
28e70 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
28e80 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
28e90 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
28ea0 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
28eb0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
28ec0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
28ed0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28ee0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
28ef0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
28f00 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
28f10 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
28f20 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
28f30 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
28f40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28f50 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
28f60 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
28f70 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
28f80 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
28f90 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
28fa0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
28fb0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
28fc0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
28fd0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
28fe0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
28ff0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
29000 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
29010 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
29020 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
29030 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
29040 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
29050 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
29060 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57  TE_MISUSE]..** W
29070 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
29080 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
29090 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
290a0 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
290b0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
290c0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
290d0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
290e0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  .**.** [SQLITE_B
290f0 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
29100 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
29110 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
29120 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
29130 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
29140 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
29150 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20  ts job.  If the 
29160 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
29170 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
29180 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
29190 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
291a0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
291b0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
291c0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
291d0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
291e0 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
291f0 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
29200 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69  hin a.** explici
29210 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
29220 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
29230 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
29240 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
29250 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
29260 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
29270 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
29280 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
29290 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
292a0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
292b0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
292c0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
292d0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
292e0 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
292f0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
29300 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
29310 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
29320 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
29330 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
29340 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
29350 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
29360 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
29370 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
29380 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
29390 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
293a0 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
293b0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
293c0 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
293d0 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
293e0 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
293f0 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
29400 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
29410 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
29420 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
29430 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
29440 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
29450 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
29460 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
29470 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
29480 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
29490 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
294a0 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
294b0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
294c0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
294d0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
294e0 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
294f0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
29500 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
29510 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
29520 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
29530 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
29540 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
29550 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69  errmsg()]..** Wi
29560 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
29570 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
29580 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
29590 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
295a0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
295b0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
295c0 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
295d0 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
295e0 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
295f0 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
29600 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
29610 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
29620 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
29630 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68  atement].  In th
29640 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
29650 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
29660 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
29670 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
29680 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
29690 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
296a0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
296b0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
296c0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
296d0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
296e0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
296f0 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
29700 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
29710 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
29720 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
29730 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
29740 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
29750 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
29760 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
29770 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
29780 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
29790 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
297a0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
297b0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
297c0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
297d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
297e0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
297f0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
29800 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
29810 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
29820 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
29830 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
29840 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
29850 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
29860 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
29870 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
29880 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
29890 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
298a0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
298b0 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
298c0 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
298d0 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
298e0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
298f0 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
29900 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
29910 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
29920 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
29930 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
29940 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
29950 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
29960 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
29970 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
29980 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
29990 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
299a0 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
299b0 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
299c0 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
299d0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
299e0 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
299f0 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
29a00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
29a10 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
29a20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29a30 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
29a40 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
29a50 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
29a60 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
29a70 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
29a80 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
29a90 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
29aa0 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
29ab0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
29ac0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
29ad0 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
29ae0 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
29af0 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
29b00 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
29b10 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
29b20 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mmended..**.** I
29b30 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
29b40 20 7b 48 31 33 32 30 32 7d 20 20 49 66 20 74 68   {H13202}  If th
29b50 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29b60 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64  ement] S is read
29b70 79 20 74 6f 20 62 65 20 72 75 6e 2c 20 74 68 65  y to be run, the
29b80 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  n.**           [
29b90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
29ba0 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 20 70   advances that p
29bb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29bc0 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20  t until.**      
29bd0 20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20       completion 
29be0 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72  or until it is r
29bf0 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 20 61  eady to return a
29c00 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68  nother row of th
29c10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  e.**           r
29c20 65 73 75 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e  esult set, or un
29c30 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  til an [sqlite3_
29c40 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65  interrupt | inte
29c50 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20  rrupt].**       
29c60 20 20 20 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d      or a run-tim
29c70 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
29c80 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20  **.** {H15304}  
29c90 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b  When a call to [
29ca0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
29cb0 20 63 61 75 73 65 73 20 74 68 65 20 5b 70 72 65   causes the [pre
29cc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29cd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 53 20  .**           S 
29ce0 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  to run to comple
29cf0 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74 69  tion, the functi
29d00 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  on returns [SQLI
29d10 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_DONE]..**.** 
29d20 7b 48 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61  {H15306}  When a
29d30 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
29d40 33 5f 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73  3_step(S)] stops
29d50 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 72   because it is r
29d60 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eady to.**      
29d70 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e 6f 74       return anot
29d80 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72  her row of the r
29d90 65 73 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65  esult set, it re
29da0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f  turns [SQLITE_RO
29db0 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30  W]..**.** {H1530
29dc0 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  8}  If a call to
29dd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
29de0 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e  )] encounters an
29df0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
29e00 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
29e10 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72   | interrupt] or
29e20 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
29e30 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  r,.**           
29e40 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  it returns an ap
29e50 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
29e60 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74  code that is not
29e70 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20   one of.**      
29e80 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
29e90 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
29ea0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
29eb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d  ..**.** {H15310}
29ec0 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33    If an [sqlite3
29ed0 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74  _interrupt | int
29ee0 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e  errupt] or a run
29ef0 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20  -time error.**  
29f00 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20           occurs 
29f10 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  during a call to
29f20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
29f30 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
29f40 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  for a [prepared 
29f50 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65  statement] S cre
29f60 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ated using.**   
29f70 20 20 20 20 20 20 20 20 6c 65 67 61 63 79 20 69          legacy i
29f80 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
29f90 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
29fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
29fb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29fc0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 75  ()], then the fu
29fd0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65  nction returns e
29fe0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
29ff0 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
2a000 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
2a010 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
2a020 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  USE]..*/.int sql
2a030 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
2a040 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2a050 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2a060 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2a070 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31  a result set {H1
2a080 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3770} <S10700>.*
2a090 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65  *.** Returns the
2a0a0 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65   number of value
2a0b0 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  s in the current
2a0c0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2a0d0 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  lt set..**.** IN
2a0e0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2a0f0 7b 48 31 33 37 37 31 7d 20 20 41 66 74 65 72 20  {H13771}  After 
2a100 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
2a110 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74  e3_step(S)] that
2a120 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
2a130 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  _ROW],.**       
2a140 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
2a150 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20  _data_count(S)] 
2a160 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
2a170 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c  urn the same val
2a180 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ue.**           
2a190 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  as the [sqlite3_
2a1a0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d  column_count(S)]
2a1b0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2a1c0 20 7b 48 31 33 37 37 32 7d 20 20 41 66 74 65 72   {H13772}  After
2a1d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2a1e0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
2a1f0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
2a200 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
2a210 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f    [SQLITE_ROW] o
2a220 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  r before [sqlite
2a230 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 62  3_step(S)] has b
2a240 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68  een called on th
2a250 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  e.**           [
2a260 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a270 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  nt] for the firs
2a280 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20  t time since it 
2a290 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  was.**          
2a2a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a2b0 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 6f 72  e | prepared] or
2a2c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 20   [sqlite3_reset 
2a2d0 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20  | reset],.**    
2a2e0 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
2a2f0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53  te3_data_count(S
2a300 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
2a310 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20  ns zero..*/.int 
2a320 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2a330 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2a340 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2a350 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
2a360 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20  ental Datatypes 
2a370 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30  {H10265} <S10110
2a380 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59  ><S10120>.** KEY
2a390 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
2a3a0 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36  XT.**.** {H10266
2a3b0 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  } Every value in
2a3c0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
2a3d0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
2a3e0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
2a3f0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2a400 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
2a410 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
2a420 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
2a430 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2a440 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
2a450 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
2a460 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
2a470 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ul> {END}.**.** 
2a480 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
2a490 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
2a4a0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
2a4b0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2a4c0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
2a4d0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
2a4e0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
2a4f0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
2a500 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
2a510 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
2a520 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
2a530 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
2a540 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
2a550 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
2a560 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
2a570 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
2a580 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
2a590 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
2a5a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2a5b0 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
2a5c0 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
2a5d0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2a5e0 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
2a5f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
2a600 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
2a610 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
2a620 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2a630 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
2a640 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
2a650 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
2a660 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
2a670 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
2a680 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
2a690 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48   From A Query {H
2a6a0 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13800} <S10700>.
2a6b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
2a6c0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2a6d0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
2a6e0 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
2a6f0 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
2a700 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63   query" interfac
2a710 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
2a720 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
2a730 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
2a740 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
2a750 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
2a760 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
2a770 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76   a query.  In ev
2a780 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
2a790 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
2a7a0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
2a7b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2a7c0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
2a7d0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
2a7e0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
2a7f0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
2a800 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
2a810 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2a820 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2a830 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
2a840 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
2a850 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2a860 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
2a870 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
2a880 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
2a890 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
2a8a0 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63    The leftmost c
2a8b0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2a8c0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
2a8d0 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49  index 0..**.** I
2a8e0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2a8f0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
2a900 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
2a910 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
2a920 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
2a930 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2a940 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
2a950 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
2a960 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2a970 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
2a980 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
2a990 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2a9a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
2a9b0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
2a9c0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2a9d0 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
2a9e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2a9f0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
2aa00 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
2aa10 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
2aa20 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
2aa30 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2aa40 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2aa50 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2aa60 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
2aa70 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2aa80 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
2aa90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2aaa0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
2aab0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
2aac0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
2aad0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2aae0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
2aaf0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
2ab00 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2ab10 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
2ab20 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
2ab30 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
2ab40 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
2ab50 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
2ab60 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2ab70 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
2ab80 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
2ab90 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2aba0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2abb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2abc0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2abd0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2abe0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2abf0 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2ac00 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2ac10 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2ac20 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68  sult column.  Th
2ac30 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
2ac40 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
2ac50 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
2ac60 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
2ac70 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
2ac80 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
2ac90 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
2aca0 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
2acb0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2acc0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2acd0 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
2ace0 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
2acf0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
2ad00 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
2ad10 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
2ad20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
2ad30 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
2ad40 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
2ad50 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2ad60 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
2ad70 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
2ad80 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2ad90 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
2ada0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
2adb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2adc0 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
2add0 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
2ade0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ion..**.** If th
2adf0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
2ae00 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
2ae10 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2ae20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ae30 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2ae40 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2ae50 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2ae60 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2ae70 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  ..** If the resu
2ae80 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
2ae90 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2aea0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2aeb0 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2aec0 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2aed0 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
2aee0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2aef0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74  f bytes..** If t
2af00 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2af10 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2af20 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2af30 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
2af40 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2af50 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
2af60 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
2af70 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
2af80 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2af90 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2afa0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2afb0 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65  .** The value re
2afc0 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
2afd0 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
2afe0 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74   terminator at t
2aff0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2b000 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c   string.  For cl
2b010 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
2b020 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65   returned is the
2b030 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
2b040 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
2b050 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
2b060 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2b070 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72  .**.** Strings r
2b080 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2b090 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2b0a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2b0b0 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
2b0c0 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
2b0d0 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
2b0e0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e  zero terminated.
2b0f0 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20    The return.** 
2b100 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
2b110 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2b120 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
2b130 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72  th BLOB is an ar
2b140 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74  bitrary.** point
2b150 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65  er, possibly eve
2b160 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
2b170 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2b180 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b190 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  16() routine is 
2b1a0 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74  similar to sqlit
2b1b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2b1c0 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20  ).** but leaves 
2b1d0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54  the result in UT
2b1e0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62  F-16 in native b
2b1f0 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61  yte order instea
2b200 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54  d of UTF-8..** T
2b210 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
2b220 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64  or is not includ
2b230 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74  ed in this count
2b240 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65  ..**.** The obje
2b250 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
2b260 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2b270 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
2b280 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2b290 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2b2a0 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
2b2b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b2c0 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
2b2d0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
2b2e0 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
2b2f0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
2b300 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2b310 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
2b320 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
2b330 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2b340 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2b350 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2b360 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2b370 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
2b380 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
2b390 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
2b3a0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2b3b0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
2b3c0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2b3d0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2b3e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2b3f0 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68  ytes()], then th
2b400 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2b410 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
2b420 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
2b430 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
2b440 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
2b450 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46   appropriate.  F
2b460 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
2b470 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
2b480 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
2b490 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
2b4a0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
2b4b0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
2b4c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
2b4d0 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
2b4e0 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
2b4f0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
2b500 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
2b510 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2b520 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2b530 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2b540 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2b550 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2b560 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2b570 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2b580 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2b590 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2b5a0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2b5b0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2b5c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2b5d0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2b5e0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2b5f0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2b600 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2b610 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2b620 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2b630 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2b640 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2b650 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2b660 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2b670 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2b680 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2b690 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2b6a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2b6b0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2b6c0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2b6d0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2b6e0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
2b6f0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2b700 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2b710 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2b720 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2b730 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
2b740 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2b750 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2b760 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
2b770 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
2b780 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2b790 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2b7a0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
2b7b0 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
2b7c0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
2b7d0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
2b7e0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
2b7f0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
2b800 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
2b810 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2b820 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2b830 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
2b840 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2b850 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
2b860 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
2b870 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2b880 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2b890 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2b8a0 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
2b8b0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
2b8c0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2b8d0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
2b8e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2b8f0 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
2b900 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2b910 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
2b920 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
2b930 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2b940 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2b950 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
2b960 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
2b970 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
2b980 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
2b990 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
2b9a0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2b9b0 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
2b9c0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2b9d0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
2b9e0 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
2b9f0 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
2ba00 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
2ba10 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
2ba20 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
2ba30 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
2ba40 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
2ba50 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
2ba60 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
2ba70 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
2ba80 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
2ba90 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
2baa0 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
2bab0 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
2bac0 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
2bad0 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
2bae0 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
2baf0 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
2bb00 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
2bb10 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
2bb20 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2bb30 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
2bb40 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
2bb50 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
2bb60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2bb70 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
2bb80 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
2bb90 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
2bba0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2bbb0 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
2bbc0 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
2bbd0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
2bbe0 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
2bbf0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
2bc00 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
2bc10 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
2bc20 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
2bc30 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2bc40 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
2bc50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2bc60 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
2bc70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2bc80 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2bc90 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
2bca0 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
2bcb0 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
2bcc0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
2bcd0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
2bce0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2bcf0 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
2bd00 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
2bd10 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
2bd20 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2bd30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2bd40 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2bd50 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2bd60 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2bd70 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
2bd80 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2bd90 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2bda0 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
2bdb0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2bdc0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2bdd0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
2bde0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
2bdf0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
2be00 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
2be10 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
2be20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
2be30 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65  /ul>.**.** Conve
2be40 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
2be50 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
2be60 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
2be70 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
2be80 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
2be90 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
2bea0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
2beb0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
2bec0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
2bed0 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
2bee0 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69  rior pointer poi
2bef0 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65  nts to will have
2bf00 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
2bf10 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
2bf20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
2bf30 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
2bf40 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
2bf50 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
2bf60 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
2bf70 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
2bf80 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
2bf90 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
2bfa0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
2bfb0 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
2bfc0 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
2bfd0 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
2bfe0 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
2bff0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
2c000 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
2c010 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
2c020 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
2c030 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c040 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
2c050 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c060 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2c070 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2c080 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
2c090 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2c0a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2c0b0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2c0c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2c0d0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2c0e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c0f0 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
2c100 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
2c110 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
2c120 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
2c130 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2c140 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
2c150 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
2c160 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c170 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
2c180 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
2c190 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
2c1a0 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
2c1b0 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
2c1c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2c1d0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
2c1e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2c1f0 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
2c200 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
2c210 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
2c220 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
2c230 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
2c240 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c250 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
2c260 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
2c270 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2c280 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
2c290 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2c2a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2c2b0 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
2c2c0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2c2d0 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
2c2e0 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   The pointers re
2c2f0 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
2c300 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
2c310 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
2c320 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
2c330 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
2c340 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c350 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
2c360 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2c370 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2c380 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2c390 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
2c3a0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
2c3b0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
2c3c0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
2c3d0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
2c3e0 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
2c3f0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2c400 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
2c410 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
2c420 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c430 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
2c440 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2c450 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  e()]..**.** If a
2c460 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2c470 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
2c480 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
2c490 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
2c4a0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2c4b0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
2c4c0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
2c4d0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
2c4e0 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
2c4f0 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
2c500 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
2c510 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
2c520 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2c530 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
2c540 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2c550 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
2c560 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
2c570 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
2c580 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
2c590 0a 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54 68 65  .** {H13803} The
2c5a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c5b0 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65  _blob(S,N)] inte
2c5c0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2c5d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
2c5e0 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
2c5f0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
2c600 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
2c610 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
2c620 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2c630 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
2c640 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20 72   BLOB and then r
2c650 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20  eturns a.**     
2c660 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20       pointer to 
2c670 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61  the converted va
2c680 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  lue..**.** {H138
2c690 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
2c6a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c  _column_bytes(S,
2c6b0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
2c6c0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
2c6d0 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
2c6e0 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f  bytes in the BLO
2c6f0 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63  B or string (exc
2c700 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
2c710 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
2c720 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
2c730 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
2c740 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
2c750 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
2c760 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2c770 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
2c780 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a  n_blob(S,N)] or.
2c790 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2c7a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c7b0 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  (S,N)]..**.** {H
2c7c0 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  13809} The [sqli
2c7d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c7e0 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
2c7f0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ce returns the.*
2c800 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
2c810 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2c820 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  e string (exclus
2c830 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
2c840 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
2c850 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
2c860 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
2c870 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2c880 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
2c890 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2c8a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c8b0 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a  ext16(S,N)]..**.
2c8c0 2a 2a 20 7b 48 31 33 38 31 32 7d 20 54 68 65 20  ** {H13812} The 
2c8d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c8e0 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74  double(S,N)] int
2c8f0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2c900 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c910 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
2c920 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
2c930 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2c940 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
2c950 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
2c960 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
2c970 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
2c980 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20   value and.**   
2c990 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
2c9a0 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61   copy of that va
2c9b0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  lue..**.** {H138
2c9c0 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  15} The [sqlite3
2c9d0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29  _column_int(S,N)
2c9e0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2c9f0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2ca00 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
2ca10 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
2ca20 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2ca30 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20   set for the.** 
2ca40 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2ca50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2ca60 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69  into a 64-bit si
2ca70 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
2ca80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2ca90 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33  urns the lower 3
2caa0 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69  2 bits of that i
2cab0 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nteger..**.** {H
2cac0 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69  13818} The [sqli
2cad0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
2cae0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
2caf0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2cb00 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
2cb10 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
2cb20 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2cb30 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68  esult set for th
2cb40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2cb50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cb60 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62  t] S into a 64-b
2cb70 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2cb80 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
2cb90 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
2cba0 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
2cbb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d  ..**.** {H13821}
2cbc0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2cbd0 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20  lumn_text(S,N)] 
2cbe0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2cbf0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2cc00 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
2cc10 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
2cc20 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2cc30 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
2cc40 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
2cc50 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2cc60 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2cc70 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20  ated UTF-8.**   
2cc80 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
2cc90 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2cca0 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2ccb0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32  ng..**.** {H1382
2ccc0 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
2ccd0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c  column_text16(S,
2cce0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
2ccf0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2cd00 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2cd10 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2cd20 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2cd30 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
2cd40 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2cd50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cd60 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  S into a zero-te
2cd70 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
2cd80 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
2cd90 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ned UTF-16 nativ
2cda0 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 72  e byte order str
2cdb0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2cdc0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f  **          a po
2cdd0 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2cde0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ring..**.** {H13
2cdf0 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  827} The [sqlite
2ce00 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c  3_column_type(S,
2ce10 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
2ce20 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
2ce30 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45    one of [SQLITE
2ce40 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NULL], [SQLITE_
2ce50 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54  INTEGER], [SQLIT
2ce60 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20  E_FLOAT],.**    
2ce70 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45        [SQLITE_TE
2ce80 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  XT], or [SQLITE_
2ce90 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72  BLOB] as appropr
2cea0 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  iate for.**     
2ceb0 20 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c       the Nth col
2cec0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2ced0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2cee0 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
2cef0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
2cf00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cf10 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  ] S..**.** {H138
2cf20 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  30} The [sqlite3
2cf30 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c  _column_value(S,
2cf40 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
2cf50 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20  turns a.**      
2cf60 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61      pointer to a
2cf70 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
2cf80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2cf90 6a 65 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ject for the.** 
2cfa0 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
2cfb0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2cfc0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2cfd0 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
2cfe0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
2cff0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d000 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ] S..*/.const vo
2d010 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2d020 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
2d030 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d040 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2d050 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
2d060 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2d070 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2d080 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2d090 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2d0a0 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
2d0b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d0c0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2d0d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d0e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2d0f0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
2d100 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d110 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
2d120 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2d130 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2d140 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
2d150 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
2d160 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2d170 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
2d180 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d190 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2d1a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d1b0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2d1c0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2d1d0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2d1e0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
2d1f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2d200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
2d210 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2d220 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2d230 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
2d240 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2d250 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
2d260 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2d270 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 30  ct {H13300} <S70
2d280 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a  300><S30100>.**.
2d290 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66  ** The sqlite3_f
2d2a0 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
2d2b0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2d2c0 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
2d2d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2d2e0 2a 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65  * If the stateme
2d2f0 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 64 20  nt was executed 
2d300 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20  successfully or 
2d310 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20  not executed at 
2d320 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  all, then.** SQL
2d330 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
2d340 65 64 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e  ed. If execution
2d350 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
2d360 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e  t failed then an
2d370 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2d380 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
2d390 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
2d3a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  urned..**.** Thi
2d3b0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
2d3c0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
2d3d0 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20  oint during the 
2d3e0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
2d3f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2d400 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68  atement].  If th
2d410 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  e virtual machin
2d420 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d  e has not.** com
2d430 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
2d440 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   when this routi
2d450 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  ne is called, th
2d460 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e  at is like.** en
2d470 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72  countering an er
2d480 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ror or an [sqlit
2d490 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
2d4a0 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e  nterrupt]..** In
2d4b0 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73  complete updates
2d4c0 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62   may be rolled b
2d4d0 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74  ack and transact
2d4e0 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a  ions canceled,.*
2d4f0 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
2d500 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  he circumstances
2d510 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72  , and the.** [er
2d520 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e  ror code] return
2d530 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49  ed will be [SQLI
2d540 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
2d550 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2d560 2a 2a 20 7b 48 31 31 33 30 32 7d 20 54 68 65 20  ** {H11302} The 
2d570 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d580 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(S)] interface 
2d590 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20  destroys the.** 
2d5a0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2d5b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2d5c0 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c  and releases all
2d5d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d  .**          mem
2d5e0 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73  ory and file res
2d5f0 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79 20 74  ources held by t
2d600 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  hat object..**.*
2d610 2a 20 7b 48 31 31 33 30 34 7d 20 49 66 20 74 68  * {H11304} If th
2d620 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2d630 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2d640 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2d650 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
2d660 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d670 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65   S returned an e
2d680 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20  rror,.**        
2d690 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
2d6a0 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74  finalize(S)] ret
2d6b0 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65  urns that same e
2d6c0 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rror..*/.int sql
2d6d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
2d6e0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2d6f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2d700 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
2d710 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2d720 4f 62 6a 65 63 74 20 7b 48 31 33 33 33 30 7d 20  Object {H13330} 
2d730 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70300>.**.** T
2d740 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
2d750 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2d760 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
2d770 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d780 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
2d790 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2d7a0 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
2d7b0 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
2d7c0 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73  ed..** Any SQL s
2d7d0 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
2d7e0 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
2d7f0 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
2d800 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
2d810 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2d820 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
2d830 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
2d840 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
2d850 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
2d860 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
2d870 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
2d880 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  dings..**.** {H1
2d890 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  1332} The [sqlit
2d8a0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2d8b0 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
2d8c0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2d8d0 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20  ement] S.**     
2d8e0 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65       back to the
2d8f0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
2d900 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
2d910 20 7b 48 31 31 33 33 34 7d 20 49 66 20 74 68 65   {H11334} If the
2d920 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2d930 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2d940 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
2d950 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2d960 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d970 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
2d980 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
2d990 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20  TE_DONE],.**    
2d9a0 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c        or if [sql
2d9b0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
2d9c0 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
2d9d0 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
2d9e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2d9f0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2da00 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
2da10 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
2da20 7b 48 31 31 33 33 36 7d 20 49 66 20 74 68 65 20  {H11336} If the 
2da30 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2da40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2da50 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2da60 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
2da70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2da80 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
2da90 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  ror, then.**    
2daa0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2dab0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2dac0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2dad0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
2dae0 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 65  .** {H11338} The
2daf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2db00 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
2db10 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2db20 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20  e values.**     
2db30 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c       of any [sql
2db40 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
2db50 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
2db60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2db70 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
2db80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
2db90 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2dba0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2dbb0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
2dbc0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
2dbd0 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53  ions {H16100} <S
2dbe0 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  20200>.** KEYWOR
2dbf0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
2dc00 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
2dc10 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2dc20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2dc30 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
2dc40 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2dc50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2dc60 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2dc70 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77  }.**.** These tw
2dc80 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  o functions (col
2dc90 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
2dca0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
2dcb0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
2dcc0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
2dcd0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
2dce0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
2dcf0 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
2dd00 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
2dd10 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
2dd20 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2dd30 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
2dd40 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74  y difference bet
2dd50 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20  ween the.** two 
2dd60 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  is that the seco
2dd70 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  nd parameter, th
2dd80 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73  e name of the (s
2dd90 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20  calar) function 
2dda0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c  or.** aggregate,
2ddb0 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55   is encoded in U
2ddc0 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33  TF-8 for sqlite3
2ddd0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2dde0 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a  () and UTF-16.**
2ddf0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
2de00 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2de10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2de20 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2de30 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2de40 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
2de50 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
2de60 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
2de70 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67  dded.  If a sing
2de80 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  le program uses 
2de90 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
2dea0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2deb0 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c  tion internally,
2dec0 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69   then SQL functi
2ded0 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
2dee0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74  d individually t
2def0 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61  o.** each databa
2df00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a  se connection..*
2df10 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
2df20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2df30 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
2df40 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2df50 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
2df60 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65  defined.  The le
2df70 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
2df80 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
2df90 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73  55 bytes, exclus
2dfa0 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65  ive of.** the ze
2dfb0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
2dfc0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
2dfd0 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  me length limit 
2dfe0 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74  is in bytes, not
2dff0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20  .** characters. 
2e000 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
2e010 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
2e020 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
2e030 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
2e040 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45  ult in [SQLITE_E
2e050 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75  RROR] being retu
2e060 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
2e070 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2e080 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
2e090 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2e0a0 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
2e0b0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2e0c0 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
2e0d0 2e 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65  . If this parame
2e0e0 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ter is negative,
2e0f0 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
2e100 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2e110 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
2e120 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
2e130 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  guments..**.** T
2e140 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2e150 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
2e160 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
2e170 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
2e180 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
2e190 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
2e1a0 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
2e1b0 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
2e1c0 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f   Any SQL functio
2e1d0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2e1e0 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20   should be able 
2e1f0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20  to work.** work 
2e200 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
2e210 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
2e220 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
2e230 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
2e240 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
2e250 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
2e260 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
2e270 74 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c  ther.  It is all
2e280 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  owed to.** invok
2e290 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2e2a0 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73  _function() or s
2e2b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2e2c0 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69  nction16() multi
2e2d0 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
2e2e0 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
2e2f0 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66  ion but with dif
2e300 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66  ferent values of
2e310 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68   eTextRep..** Wh
2e320 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
2e330 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2e340 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2e350 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
2e360 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
2e370 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
2e380 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
2e390 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
2e3a0 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
2e3b0 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
2e3c0 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
2e3d0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
2e3e0 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
2e3f0 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f  hat text.** enco
2e400 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
2e410 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
2e420 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
2e430 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a   [SQLITE_ANY]..*
2e440 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70  *.** The fifth p
2e450 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
2e460 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
2e470 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
2e480 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
2e490 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69  function can gai
2e4a0 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73  n access to this
2e4b0 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b   pointer using [
2e4c0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2e4d0 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  a()]..**.** The 
2e4e0 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20  seventh, eighth 
2e4f0 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  and ninth parame
2e500 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
2e510 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
2e520 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
2e530 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
2e540 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
2e550 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
2e560 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2e570 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72  regate. A scalar
2e580 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2e590 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2e5a0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
2e5b0 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
2e5c0 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69  k only, NULL poi
2e5d0 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20  nters should be 
2e5e0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
2e5f0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
2e600 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e  * parameters. An
2e610 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2e620 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
2e630 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
2e640 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
2e650 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
2e660 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  LL should be pas
2e670 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54  sed for xFunc. T
2e680 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
2e690 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
2e6a0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2e6b0 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72  e, pass NULL for
2e6c0 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
2e6d0 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  ion callbacks..*
2e6e0 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69  *.** It is permi
2e6f0 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
2e700 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2e710 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2e720 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
2e730 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
2e740 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
2e750 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
2e760 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
2e770 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
2e780 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
2e790 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
2e7a0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
2e7b0 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
2e7c0 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65  ation most close
2e7d0 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
2e7e0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
2e7f0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2e800 69 73 20 75 73 65 64 2e 20 20 41 20 66 75 6e 63  is used.  A func
2e810 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2e820 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
2e830 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
2e840 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
2e850 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
2e860 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
2e870 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
2e880 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
2e890 72 67 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20  rg.  A function 
2e8a0 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
2e8b0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2e8c0 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
2e8d0 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
2e8e0 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
2e8f0 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
2e900 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2e910 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
2e920 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 20  fferent.  .** A 
2e930 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2e940 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
2e950 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
2e960 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
2e970 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
2e980 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
2e990 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
2e9a0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
2e9b0 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
2e9c0 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
2e9d0 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69  UTF16..**.** Bui
2e9e0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
2e9f0 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
2ea00 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
2ea10 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2ea20 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 66  ctions..** The f
2ea30 69 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  irst application
2ea40 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2ea50 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e  n with a given n
2ea60 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c  ame overrides al
2ea70 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75  l.** built-in fu
2ea80 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73  nctions in the s
2ea90 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
2eaa0 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74  nnection] with t
2eab0 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
2eac0 20 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c   Subsequent appl
2ead0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2eae0 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65  functions of the
2eaf0 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20   same name only 
2eb00 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69  override .** pri
2eb10 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  or application-d
2eb20 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
2eb30 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 61   that are an exa
2eb40 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65  ct match for the
2eb50 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  .** number of pa
2eb60 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65  rameters and pre
2eb70 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e  ferred encoding.
2eb80 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 63  .**.** An applic
2eb90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2eba0 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
2ebb0 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
2ebc0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
2ebd0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
2ebe0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
2ebf0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
2ec00 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2ec10 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
2ec20 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
2ec30 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec40 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
2ec50 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
2ec60 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49  running..**.** I
2ec70 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2ec80 20 7b 48 31 36 31 30 33 7d 20 54 68 65 20 5b 73   {H16103} The [s
2ec90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2eca0 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 2e 2e 2e  nction16(D,X,...
2ecb0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
2ecc0 6c 6c 20 62 65 68 61 76 65 0a 2a 2a 20 20 20 20  ll behave.**    
2ecd0 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65        as [sqlite
2ece0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ecf0 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 20 65  n(D,X,...)] in e
2ed00 76 65 72 79 20 77 61 79 20 65 78 63 65 70 74 20  very way except 
2ed10 74 68 61 74 20 69 74 0a 2a 2a 20 20 20 20 20 20  that it.**      
2ed20 20 20 20 20 69 6e 74 65 72 70 72 65 74 73 20 74      interprets t
2ed30 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 61 73  he X argument as
2ed40 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2ed50 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20   UTF-16.**      
2ed60 20 20 20 20 6e 61 74 69 76 65 20 62 79 74 65 20      native byte 
2ed70 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
2ed80 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   as zero-termina
2ed90 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  ted UTF-8..**.**
2eda0 20 7b 48 31 36 31 30 36 7d 20 41 20 73 75 63 63   {H16106} A succ
2edb0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
2edc0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  n of the.**     
2edd0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72       [sqlite3_cr
2ede0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2edf0 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65  X,N,E,...)] inte
2ee00 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67 69  rface shall regi
2ee10 73 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ster.**         
2ee20 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c   or replaces cal
2ee30 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
2ee40 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  in the [database
2ee50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
2ee60 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 64 20  *          used 
2ee70 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  to implement the
2ee80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61   SQL function na
2ee90 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70 61 72  med X with N par
2eea0 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  ameters.**      
2eeb0 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67 20 61      and having a
2eec0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2eed0 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a  encoding of E..*
2eee0 2a 0a 2a 2a 20 7b 48 31 36 31 30 39 7d 20 41 20  *.** {H16109} A 
2eef0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
2ef00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2ef10 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2ef20 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a  N,E,P,F,S,L)].**
2ef30 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
2ef40 72 65 70 6c 61 63 65 20 74 68 65 20 50 2c 20 46  replace the P, F
2ef50 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65  , S, and L value
2ef60 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72  s from any prior
2ef70 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20   calls with.**  
2ef80 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
2ef90 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20   D, X, N, and E 
2efa0 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  values..**.** {H
2efb0 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  16112} The [sqli
2efc0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2efd0 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e  ion(D,X,...)] in
2efe0 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 66 61  terface shall fa
2eff0 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  il.**          i
2f000 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2f010 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20  on name X is.** 
2f020 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20           longer 
2f030 74 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65  than 255 bytes e
2f040 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
2f050 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2f060 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20  .**.** {H16118} 
2f070 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2f080 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2f090 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 69  ,N,E,P,F,S,L)] i
2f0a0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20  nterface.**     
2f0b0 20 20 20 20 20 73 68 61 6c 6c 20 66 61 69 6c 20       shall fail 
2f0c0 75 6e 6c 65 73 73 20 65 69 74 68 65 72 20 46 20  unless either F 
2f0d0 69 73 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e  is NULL and S an
2f0e0 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c  d L are non-NULL
2f0f0 20 6f 72 0a 2a 2a 2a 20 20 20 20 20 20 20 20 20   or.***         
2f100 46 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e  F is non-NULL an
2f110 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55  d S and L are NU
2f120 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32  LL..**.** {H1612
2f130 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
2f140 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2f150 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  D,...)] interfac
2f160 65 20 73 68 61 6c 6c 20 66 61 69 6c 73 20 77 69  e shall fails wi
2f170 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  th an.**        
2f180 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20    error code of 
2f190 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66  [SQLITE_BUSY] if
2f1a0 20 74 68 65 72 65 20 65 78 69 73 74 20 5b 70 72   there exist [pr
2f1b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f1c0 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  s].**          a
2f1d0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
2f1e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2f1f0 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
2f200 2a 20 7b 48 31 36 31 32 34 7d 20 54 68 65 20 5b  * {H16124} The [
2f210 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f220 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
2f230 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  .)] interface sh
2f240 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a  all fail with.**
2f250 20 20 20 20 20 20 20 20 20 20 61 6e 20 65 72 72            an err
2f260 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
2f270 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61 72  TE_ERROR] if par
2f280 61 6d 65 74 65 72 20 4e 20 69 73 20 6c 65 73 73  ameter N is less
2f290 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
2f2a0 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
2f2b0 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20  than 127..**.** 
2f2c0 7b 48 31 36 31 32 37 7d 20 57 68 65 6e 20 4e 20  {H16127} When N 
2f2d0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
2f2e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2f2f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2f300 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  X,N,...)].**    
2f310 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
2f320 73 68 61 6c 6c 20 72 65 67 69 73 74 65 72 20 63  shall register c
2f330 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69  allbacks to be i
2f340 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 0a 2a  nvoked for the.*
2f350 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 66  *          SQL f
2f360 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  unction.**      
2f370 20 20 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e      named X when
2f380 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
2f390 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2f3a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  SQL function is.
2f3b0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 61 63  **          exac
2f3c0 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tly N..**.** {H1
2f3d0 36 31 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20  6130} When N is 
2f3e0 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  -1, the [sqlite3
2f3f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2f400 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (D,X,N,...)].** 
2f410 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
2f420 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74 65  ce shall registe
2f430 72 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62  r callbacks to b
2f440 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  e invoked for th
2f450 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20  e SQL.**        
2f460 20 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64    function named
2f470 20 58 20 77 69 74 68 20 61 6e 79 20 6e 75 6d 62   X with any numb
2f480 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e  er of arguments.
2f490 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 33 7d 20  .**.** {H16133} 
2f4a0 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  When calls to [s
2f4b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f4c0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e  nction(D,X,N,...
2f4d0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  )].**          s
2f4e0 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20  pecify multiple 
2f4f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2f500 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2f510 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20  tion X.**       
2f520 20 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20     and when one 
2f530 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68  implementation h
2f540 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20  as N>=0 and the 
2f550 6f 74 68 65 72 20 68 61 73 20 4e 3d 28 2d 31 29  other has N=(-1)
2f560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2f570 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f580 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  with a non-zero 
2f590 4e 20 73 68 61 6c 6c 20 62 65 20 70 72 65 66 65  N shall be prefe
2f5a0 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  rred..**.** {H16
2f5b0 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20  136} When calls 
2f5c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2f5d0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2f5e0 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  N,E,...)].**    
2f5f0 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75        specify mu
2f600 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2f610 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2f620 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  me function X wi
2f630 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
2f640 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f  he same number o
2f650 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20 62 75  f arguments N bu
2f660 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
2f670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63  .**          enc
2f680 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e 20 74  odings E, then t
2f690 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2f6a0 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63 68 65  n where E matche
2f6b0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2f6c0 20 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64    database encod
2f6d0 69 6e 67 20 73 68 61 6c 6c 20 70 72 65 66 65 72  ing shall prefer
2f6e0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  red..**.** {H161
2f6f0 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67 72 65  39} For an aggre
2f700 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2f710 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  n created using.
2f720 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2f730 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f740 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30  tion(D,X,N,E,P,0
2f750 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c  ,S,L)] the final
2f760 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  izer.**         
2f770 20 66 75 6e 63 74 69 6f 6e 20 4c 20 73 68 61 6c   function L shal
2f780 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e 76 6f  l always be invo
2f790 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  ked exactly once
2f7a0 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   if the.**      
2f7b0 20 20 20 20 73 74 65 70 20 66 75 6e 63 74 69 6f      step functio
2f7c0 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  n S is called on
2f7d0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
2f7e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34 32 7d 20  .**.** {H16142} 
2f7f0 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
2f800 6b 65 73 20 65 69 74 68 65 72 20 74 68 65 20 78  kes either the x
2f810 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20 66 75  Func or xStep fu
2f820 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20  nction of.**    
2f830 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69 63 61        an applica
2f840 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2f850 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2f860 72 65 67 61 74 65 20 63 72 65 61 74 65 64 0a 2a  regate created.*
2f870 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73  *          by [s
2f880 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f890 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71  nction()] or [sq
2f8a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f8b0 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20  ction16()],.**  
2f8c0 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
2f8d0 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c 69 74   array of [sqlit
2f8e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2f8f0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  s passed as the.
2f900 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 69 72  **          thir
2f910 64 20 70 61 72 61 6d 65 74 65 72 20 73 68 61 6c  d parameter shal
2f920 6c 20 62 65 20 5b 70 72 6f 74 65 63 74 65 64 20  l be [protected 
2f930 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2f940 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73  bjects..*/.int s
2f950 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f960 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
2f970 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
2f980 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
2f990 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2f9a0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2f9b0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2f9c0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2f9d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2f9e0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2f9f0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2fa00 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2fa10 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2fa20 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2fa30 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2fa40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2fa50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2fa60 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2fa70 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2fa80 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
2fa90 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2faa0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2fab0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2fac0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2fad0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2fae0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2faf0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2fb00 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2fb10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2fb20 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2fb30 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2fb40 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2fb50 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  ntext*).);../*.*
2fb60 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
2fb70 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32   Encodings {H102
2fb80 36 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31  67} <S50200> <H1
2fb90 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6100>.**.** Thes
2fba0 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
2fbb0 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
2fbc0 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
2fbd0 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
2fbe0 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
2fbf0 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
2fc00 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2fc10 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
2fc20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2fc30 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
2fc40 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2fc50 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
2fc60 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2fc70 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
2fc80 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
2fc90 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2fca0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2fcb0 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
2fcc0 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
2fcd0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2fce0 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
2fcf0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
2fd00 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
2fd10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2fd20 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
2fd30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fd40 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
2fd50 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
2fd60 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
2fd70 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
2fd80 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
2fd90 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
2fda0 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
2fdb0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
2fdc0 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
2fdd0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
2fde0 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
2fdf0 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
2fe00 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
2fe10 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
2fe20 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
2fe30 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2fe40 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
2fe50 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
2fe60 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
2fe70 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
2fe80 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
2fe90 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68  g to tell you wh
2fea0 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
2feb0 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
2fec0 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
2fed0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2fee0 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
2fef0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
2ff00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
2ff10 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2ff20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70   int sqlite3_exp
2ff30 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
2ff40 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2ff50 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2ff60 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
2ff70 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2ff80 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
2ff90 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
2ffa0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2ffb0 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
2ffc0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
2ffd0 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
2ffe0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
2fff0 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
30000 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
30010 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
30020 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
30030 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
30040 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73  t64,int),void*,s
30050 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23  qlite3_int64);.#
30060 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
30070 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
30080 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61   SQL Function Pa
30090 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b  rameter Values {
300a0 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e  H15100} <S20200>
300b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
300c0 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
300d0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
300e0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
300f0 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
30100 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
30110 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
30120 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
30130 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
30140 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
30150 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
30160 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
30170 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
30180 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
30190 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
301a0 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
301b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
301c0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
301d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
301e0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
301f0 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
30200 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
30210 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
30220 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
30230 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61  .** The 4th para
30240 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
30250 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
30260 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
30270 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
30280 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30290 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
302a0 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
302b0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
302c0 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
302d0 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
302e0 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
302f0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
30300 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
30310 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
30320 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
30330 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
30340 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
30350 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
30360 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30370 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
30380 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
30390 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
303a0 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
303b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
303c0 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
303d0 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
303e0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
303f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
30400 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
30410 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
30420 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
30430 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
30440 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
30450 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
30460 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
30470 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
30480 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
30490 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
304a0 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
304b0 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
304c0 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
304d0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
304e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
304f0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
30500 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
30510 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
30520 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
30530 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
30540 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
30550 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
30560 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
30570 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
30580 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
30590 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
305a0 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
305b0 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
305c0 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
305d0 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
305e0 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
305f0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
30600 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
30610 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
30620 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
30630 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
30640 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
30650 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
30660 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
30670 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
30680 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
30690 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
306a0 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
306b0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
306c0 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
306d0 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
306e0 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
306f0 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
30700 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
30710 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
30720 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
30730 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
30740 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
30750 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
30760 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
30770 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
30780 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
30790 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
307a0 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
307b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  ed..**.** Please
307c0 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
307d0 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
307e0 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
307f0 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
30800 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
30810 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
30820 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30830 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
30840 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30850 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
30860 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
30870 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
30880 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
30890 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
308a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
308b0 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
308c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
308d0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
308e0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
308f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
30900 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
30910 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
30920 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
30930 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
30940 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
30950 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30960 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
30970 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
30980 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 33 7d  :.**.** {H15103}
30990 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
309a0 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74  lue_blob(V)] int
309b0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
309c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
309d0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
309e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
309f0 20 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61   V into a BLOB a
30a00 6e 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  nd then.**      
30a10 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 70 6f      returns a po
30a20 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e  inter to the con
30a30 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a  verted value..**
30a40 0a 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54 68 65  .** {H15106} The
30a50 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30a60 62 79 74 65 73 28 56 29 5d 20 69 6e 74 65 72 66  bytes(V)] interf
30a70 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
30a80 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
30a90 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
30aa0 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
30ab0 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20  g (exclusive of 
30ac0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
30ad0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
30ae0 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74  on the string) t
30af0 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
30b00 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   by the.**      
30b10 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20      most recent 
30b20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
30b30 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20  _value_blob(V)] 
30b40 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
30b50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30b60 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  xt(V)]..**.** {H
30b70 31 35 31 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  15109} The [sqli
30b80 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
30b90 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  6(V)] interface 
30ba0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
30bb0 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
30bc0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  f bytes in the s
30bd0 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
30be0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
30bf0 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
30c00 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
30c10 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
30c20 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
30c30 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
30c40 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
30c50 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30c60 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  6(V)],.**       
30c70 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75     [sqlite3_valu
30c80 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 2c 20  e_text16be(V)], 
30c90 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
30ca0 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a  e_text16le(V)]..
30cb0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d 20 54  **.** {H15112} T
30cc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30cd0 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74  e_double(V)] int
30ce0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
30cf0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
30d00 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
30d10 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30d20 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69   V into a floati
30d30 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61  ng point value a
30d40 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
30d50 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
30d60 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a   that value..**.
30d70 2a 2a 20 7b 48 31 35 31 31 35 7d 20 54 68 65 20  ** {H15115} The 
30d80 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
30d90 6e 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  nt(V)] interface
30da0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
30db0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
30dc0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
30dd0 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
30de0 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65  o a 64-bit signe
30df0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a  d integer and.**
30e00 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
30e10 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62  s the lower 32 b
30e20 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65  its of that inte
30e30 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  ger..**.** {H151
30e40 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  18} The [sqlite3
30e50 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d  _value_int64(V)]
30e60 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
30e70 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
30e80 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
30e90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30ea0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34  ject V into a 64
30eb0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
30ec0 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
30ed0 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
30ee0 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  py of that integ
30ef0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32  er..**.** {H1512
30f00 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
30f10 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 20 69  value_text(V)] i
30f20 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
30f30 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
30f40 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
30f50 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30f60 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
30f70 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
30f80 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  8.**          st
30f90 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
30fa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
30fb0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
30fc0 20 7b 48 31 35 31 32 34 7d 20 54 68 65 20 5b 73   {H15124} The [s
30fd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30fe0 74 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63  t16(V)] interfac
30ff0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
31000 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
31010 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
31020 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
31030 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
31040 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
31050 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
31060 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
31070 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20  te order.**     
31080 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
31090 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
310a0 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
310b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 37 7d  ..**.** {H15127}
310c0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
310d0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d  lue_text16be(V)]
310e0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
310f0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
31100 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
31110 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
31120 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
31130 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d  ro-terminated 2-
31140 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  byte.**         
31150 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20   aligned UTF-16 
31160 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20  big-endian.**   
31170 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
31180 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
31190 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
311a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33  ng..**.** {H1513
311b0 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  0} The [sqlite3_
311c0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56  value_text16le(V
311d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
311e0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
311f0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
31200 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
31210 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
31220 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
31230 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
31240 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
31250 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a  6 little-endian.
31260 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
31270 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
31280 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
31290 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
312a0 48 31 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c  H15133} The [sql
312b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
312c0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
312d0 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
312e0 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45    one of [SQLITE
312f0 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NULL], [SQLITE_
31300 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54  INTEGER], [SQLIT
31310 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20  E_FLOAT],.**    
31320 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45        [SQLITE_TE
31330 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  XT], or [SQLITE_
31340 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72  BLOB] as appropr
31350 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  iate for.**     
31360 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
31370 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
31380 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 36  V..**.** {H15136
31390 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
313a0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
313b0 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
313c0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20  converts.**     
313d0 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63       the [protec
313e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
313f0 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
31400 20 65 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67   either an integ
31410 65 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  er or.**        
31420 20 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69    a floating poi
31430 6e 74 20 76 61 6c 75 65 20 69 66 20 69 74 20 63  nt value if it c
31440 61 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74  an do so without
31450 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20   loss of.**     
31460 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e       information
31470 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e  , and returns on
31480 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  e of [SQLITE_NUL
31490 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  L],.**          
314a0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
314b0 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  , [SQLITE_FLOAT]
314c0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
314d0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
314e0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73  [SQLITE_BLOB] as
314f0 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
31500 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
31510 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
31520 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
31530 74 20 56 20 61 66 74 65 72 20 74 68 65 20 63 6f  t V after the co
31540 6e 76 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74  nversion attempt
31550 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
31560 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
31570 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
31580 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
31590 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
315a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
315b0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
315c0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
315d0 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20  value*);.double 
315e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
315f0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
31600 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
31610 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
31620 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c  te3_value*);.sql
31630 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
31640 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
31650 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31660 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
31670 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  har *sqlite3_val
31680 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  ue_text(sqlite3_
31690 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
316a0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
316b0 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
316c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
316d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
316e0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
316f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
31700 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31710 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
31720 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
31730 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
31740 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
31750 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
31760 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
31770 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
31780 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
31790 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
317a0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
317b0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48  ction Context {H
317c0 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16210} <S20200>.
317d0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d  **.** The implem
317e0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72  entation of aggr
317f0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
31800 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75  ons use this rou
31810 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
31820 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20  .** a structure 
31830 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
31840 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  r state..**.** T
31850 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
31860 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
31870 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f  ate_context() ro
31880 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
31890 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75  for a.** particu
318a0 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 53  lar aggregate, S
318b0 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20  QLite allocates 
318c0 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79  nBytes of memory
318d0 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
318e0 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  t.** memory, and
318f0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
31900 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63  er to it. On sec
31910 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
31920 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
31930 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31940 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
31950 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
31960 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78  e function index
31970 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
31980 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
31990 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  . The implementa
319a0 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72  tion of the aggr
319b0 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a  egate can use.**
319c0 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62 75   the returned bu
319d0 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61  ffer to accumula
319e0 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  te data..**.** S
319f0 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
31a00 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 61 6c  lly frees the al
31a10 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 20 77  located buffer w
31a20 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
31a30 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c  e.** query concl
31a40 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
31a50 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
31a60 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79  should be a copy
31a70 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
31a80 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
31a90 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
31aa0 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
31ab0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
31ac0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
31ad0 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
31ae0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
31af0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
31b00 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
31b10 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
31b20 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
31b30 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
31b40 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
31b50 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
31b60 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
31b70 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
31b80 2a 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20 54 68  *.** {H16211} Th
31b90 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69  e first invocati
31ba0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61  on of [sqlite3_a
31bb0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
31bc0 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20  (C,N)] for.**   
31bd0 20 20 20 20 20 20 20 61 20 70 61 72 74 69 63 75         a particu
31be0 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  lar instance of 
31bf0 61 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  an aggregate fun
31c00 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72  ction (for a par
31c10 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20  ticular.**      
31c20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63      context C) c
31c30 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
31c40 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74 65 73  allocate N bytes
31c50 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20   of memory,.**  
31c60 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61          zero tha
31c70 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
31c80 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  turn a pointer t
31c90 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  o the allocated 
31ca0 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  memory..**.** {H
31cb0 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f  16213} If a memo
31cc0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
31cd0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
31ce0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
31cf0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31d00 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74  _context(C,N)] t
31d10 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
31d20 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a   returns 0..**.*
31d30 2a 20 7b 48 31 36 32 31 35 7d 20 53 65 63 6f 6e  * {H16215} Secon
31d40 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
31d50 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a   invocations of.
31d60 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
31d70 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31d80 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72  ontext(C,N)] for
31d90 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78   the same contex
31da0 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20  t pointer C.**  
31db0 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74          ignore t
31dc0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61  he N parameter a
31dd0 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  nd return a poin
31de0 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a  ter to the same.
31df0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63  **          bloc
31e00 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75  k of memory retu
31e10 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73  rned by the firs
31e20 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  t invocation..**
31e30 0a 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54 68 65  .** {H16217} The
31e40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
31e50 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67  d by [sqlite3_ag
31e60 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31e70 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20  C,N)] is.**     
31e80 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c       automatical
31e90 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20  ly freed on the 
31ea0 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  next call to [sq
31eb0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
31ec0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
31ed0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
31ee0 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  )] for the [prep
31ef0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31f00 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20  containing.**   
31f10 20 20 20 20 20 20 20 74 68 65 20 61 67 67 72 65         the aggre
31f20 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73  gate function as
31f30 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f  sociated with co
31f40 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64  ntext C..*/.void
31f50 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
31f60 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
31f70 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
31f80 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
31f90 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
31fa0 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
31fb0 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c 53 32  ons {H16240} <S2
31fc0 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
31fd0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
31fe0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
31ff0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
32000 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
32010 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
32020 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
32030 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
32040 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
32050 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32060 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
32070 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
32080 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
32090 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
320a0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
320b0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
320c0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
320d0 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a  nction. {END}.**
320e0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
320f0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
32100 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
32110 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
32120 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32130 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
32140 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
32150 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
32160 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d 20 54  **.** {H16243} T
32170 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  he [sqlite3_user
32180 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65 72 66  _data(C)] interf
32190 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
321a0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  py of the.**    
321b0 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65 72 20        P pointer 
321c0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
321d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
321e0 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
321f0 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  L)].**          
32200 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
32210 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c  te_function16(D,
32220 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20  X,N,E,P,F,S,L)] 
32230 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20  call that.**    
32240 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
32250 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32260 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  n associated wit
32270 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  h [sqlite3_conte
32280 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  xt] C..*/.void *
32290 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
322a0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
322b0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
322c0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
322d0 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
322e0 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d  nctions {H16250}
322f0 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30   <S60600><S20200
32300 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
32310 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
32320 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
32330 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
32340 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
32350 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
32360 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
32370 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
32380 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
32390 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
323a0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
323b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
323c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
323d0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
323e0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
323f0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
32400 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
32410 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e  nction..**.** IN
32420 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
32430 7b 48 31 36 32 35 33 7d 20 54 68 65 20 5b 73 71  {H16253} The [sq
32440 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
32450 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65  _handle(C)] inte
32460 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
32470 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
32480 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e 74 65          D pointe
32490 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  r from the [sqli
324a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
324b0 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
324c0 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
324d0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72    or [sqlite3_cr
324e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
324f0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
32500 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20  ] call that.**  
32510 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
32520 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ed the SQL funct
32530 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
32540 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ith [sqlite3_con
32550 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69  text] C..*/.sqli
32560 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
32570 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
32580 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32590 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
325a0 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
325b0 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 32  liary Data {H162
325c0 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  70} <S20200>.**.
325d0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
325e0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
325f0 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
32600 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
32610 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
32620 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
32630 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
32640 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
32650 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
32660 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
32670 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
32680 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
32690 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
326a0 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
326b0 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
326c0 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
326d0 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
326e0 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
326f0 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
32700 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
32710 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
32720 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
32730 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
32740 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
32750 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
32760 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
32770 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
32780 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
32790 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
327a0 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
327b0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
327c0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
327d0 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
327e0 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
327f0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
32800 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
32810 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
32820 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
32830 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
32840 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
32850 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
32860 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
32870 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
32880 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
32890 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
328a0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
328b0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
328c0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
328d0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
328e0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
328f0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
32900 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
32910 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
32920 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
32930 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
32940 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32950 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f   function. If no
32960 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
32970 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20  en ever.** been 
32980 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20  set for the Nth 
32990 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
329a0 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
329b0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
329c0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  g.** function pa
329d0 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e  rameter has chan
329e0 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
329f0 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
32a00 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
32a10 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72  _get_auxdata() r
32a20 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
32a30 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
32a40 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
32a50 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
32a60 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
32a70 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
32a80 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
32a90 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
32aa0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
32ab0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
32ac0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
32ad0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32ae0 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
32af0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
32b00 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
32b10 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
32b20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
32b30 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
32b40 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49   destroyed..** I
32b50 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
32b60 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  , SQLite will in
32b70 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
32b80 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  tor.** function 
32b90 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68  given by the 4th
32ba0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
32bb0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
32bc0 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65  a() on.** the me
32bd0 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20  tadata when the 
32be0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
32bf0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
32c00 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77   changes.** or w
32c10 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
32c20 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c  ement completes,
32c30 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
32c40 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51   first..**.** SQ
32c50 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
32c60 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63  call the destruc
32c70 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74  tor and drop met
32c80 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20  adata on any.** 
32c90 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79  parameter of any
32ca0 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79   function at any
32cb0 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79   time.  The only
32cc0 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68   guarantee is th
32cd0 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75  at.** the destru
32ce0 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c  ctor will be cal
32cf0 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d  led before the m
32d00 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70  etadata is dropp
32d10 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61  ed..**.** In pra
32d20 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
32d30 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
32d40 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
32d50 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65  lls for.** expre
32d60 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ssions that are 
32d70 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70  constant at comp
32d80 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69  ile time. This i
32d90 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a  ncludes literal.
32da0 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51  ** values and SQ
32db0 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a  L variables..**.
32dc0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
32dd0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
32de0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
32df0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
32e00 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
32e10 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
32e20 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
32e30 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32 7d 20  .**.** {H16272} 
32e40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  The [sqlite3_get
32e50 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20 69  _auxdata(C,N)] i
32e60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
32e70 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
32e80 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64 61         to metada
32e90 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
32ea0 74 68 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d  th the Nth param
32eb0 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20  eter of the SQL 
32ec0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
32ed0 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74 65       whose conte
32ee0 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c  xt is C, or NULL
32ef0 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   if there is no 
32f00 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
32f10 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
32f20 77 69 74 68 20 74 68 61 74 20 70 61 72 61 6d 65  with that parame
32f30 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  ter..**.** {H162
32f40 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  74} The [sqlite3
32f50 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
32f60 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,P,D)] interface
32f70 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61 64   assigns a metad
32f80 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ata.**          
32f90 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68 65  pointer P to the
32fa0 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   Nth parameter o
32fb0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
32fc0 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20  on with context 
32fd0 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 36  C..**.** {H16276
32fe0 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  } SQLite will in
32ff0 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
33000 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e  tor D with a sin
33010 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  gle argument.** 
33020 20 20 20 20 20 20 20 20 20 77 68 69 63 68 20 69           which i
33030 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 70  s the metadata p
33040 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69  ointer P followi
33050 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ng a call to.** 
33060 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
33070 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
33080 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c  N,P,D)] when SQL
33090 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f  ite ceases to ho
330a0 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ld.**          t
330b0 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a  he metadata..**.
330c0 2a 2a 20 7b 48 31 36 32 37 37 7d 20 53 51 4c 69  ** {H16277} SQLi
330d0 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c  te ceases to hol
330e0 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61  d metadata for a
330f0 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  n SQL function p
33100 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
33110 20 20 20 20 20 77 68 65 6e 20 74 68 65 20 76 61       when the va
33120 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61 72 61  lue of that para
33130 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a  meter changes..*
33140 2a 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20 57 68  *.** {H16278} Wh
33150 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  en [sqlite3_set_
33160 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29  auxdata(C,N,P,D)
33170 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  ] is invoked, th
33180 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
33190 20 20 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c           is call
331a0 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72  ed for any prior
331b0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
331c0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ated with the sa
331d0 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  me function.**  
331e0 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20          context 
331f0 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20  C and parameter 
33200 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 39  N..**.** {H16279
33210 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61  } SQLite will ca
33220 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20 66  ll destructors f
33230 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20  or any metadata 
33240 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a  it is holding.**
33250 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 20 70            in a p
33260 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61  articular [prepa
33270 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
33280 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20   when either.** 
33290 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
332a0 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b  3_reset(S)] or [
332b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
332c0 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a  (S)] is called..
332d0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
332e0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
332f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
33300 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt N);.void sqli
33310 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
33320 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33330 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
33340 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
33350 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
33360 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
33370 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
33380 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
33390 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 33 30  or {H10280} <S30
333a0 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  100>.**.** These
333b0 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
333c0 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
333d0 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
333e0 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
333f0 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
33400 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
33410 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
33420 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20  lt_blob()].  If 
33430 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
33440 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
33450 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
33460 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
33470 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
33480 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
33490 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
334a0 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
334b0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
334c0 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20  troyed.  The.** 
334d0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
334e0 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61   value means tha
334f0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69  t the content wi
33500 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65  ll likely change
33510 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20   in.** the near 
33520 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20  future and that 
33530 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61  SQLite should ma
33540 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ke its own priva
33550 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68  te copy of.** th
33560 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65  e content before
33570 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
33580 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73  * The typedef is
33590 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f   necessary to wo
335a0 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65  rk around proble
335b0 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a  ms in certain.**
335c0 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20   C++ compilers. 
335d0 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39   See ticket #219
335e0 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  1..*/.typedef vo
335f0 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
33600 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
33610 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
33620 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
33630 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
33640 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
33650 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
33660 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
33670 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
33680 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
33690 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
336a0 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
336b0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48   SQL Function {H
336c0 31 36 34 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16400} <S20200>.
336d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
336e0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
336f0 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
33700 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
33710 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
33720 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
33730 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
33740 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
33750 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
33760 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
33770 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
33780 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
33790 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
337a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
337b0 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
337c0 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
337d0 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  e [parameter bin
337e0 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  ding] family of.
337f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  ** functions use
33800 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  d to bind values
33810 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
33820 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
33830 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
33840 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c  efer to the [SQL
33850 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75   parameter] docu
33860 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
33870 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
33880 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
33890 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
338a0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
338b0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
338c0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
338d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
338e0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
338f0 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
33900 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
33910 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
33920 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
33930 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
33940 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
33950 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
33960 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
33970 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
33980 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
33990 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
339a0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
339b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
339c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
339d0 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
339e0 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
339f0 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
33a00 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
33a10 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
33a20 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
33a30 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
33a40 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33a50 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
33a60 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
33a70 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
33a80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33a90 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
33aa0 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
33ab0 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
33ac0 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
33ad0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
33ae0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
33af0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
33b00 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33b10 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
33b20 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
33b30 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
33b40 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
33b50 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
33b60 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  ..** SQLite uses
33b70 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
33b80 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
33b90 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
33ba0 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
33bb0 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
33bc0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33bd0 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
33be0 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
33bf0 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65  message.  SQLite
33c00 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
33c10 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
33c20 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
33c30 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33c40 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51  r() as UTF-8. SQ
33c50 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
33c60 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
33c70 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
33c80 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
33c90 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
33ca0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
33cb0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
33cc0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
33cd0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
33ce0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
33cf0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
33d00 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
33d10 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
33d20 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
33d30 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
33d40 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
33d50 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
33d60 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68  er..** If the th
33d70 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
33d80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33d90 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
33da0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33db0 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
33dc0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
33dd0 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
33de0 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
33df0 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
33e00 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
33e10 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
33e20 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65   message..** The
33e30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33e40 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
33e50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33e60 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
33e70 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
33e80 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
33e90 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
33ea0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
33eb0 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
33ec0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
33ed0 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
33ee0 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
33ef0 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
33f00 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
33f10 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73  t harm..** The s
33f20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33f30 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
33f40 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
33f50 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
33f60 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
33f70 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
33f80 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
33f90 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61  nction.  By defa
33fa0 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
33fb0 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
33fc0 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65  _ERROR.  A subse
33fd0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
33fe0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33ff0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
34000 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
34010 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
34020 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
34030 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
34040 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
34050 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
34060 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
34070 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
34080 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
34090 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
340a0 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
340b0 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
340c0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nt..**.** The sq
340d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d  lite3_result_nom
340e0 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  em() interface c
340f0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
34100 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
34110 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
34120 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  t a memory alloc
34130 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a  ation failed..**
34140 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
34150 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
34160 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
34170 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
34180 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
34190 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
341a0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
341b0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
341c0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
341d0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
341e0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73  gument..** The s
341f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
34200 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
34210 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
34220 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
34230 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34240 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
34250 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
34260 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
34270 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
34280 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
34290 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
342a0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
342b0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
342c0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
342d0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
342e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
342f0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
34300 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  LL..**.** The sq
34310 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34320 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
34330 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
34340 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34350 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
34360 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34370 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
34380 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
34390 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
343a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
343b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
343c0 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
343d0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
343e0 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
343f0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
34400 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
34410 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
34420 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
34430 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
34440 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
34450 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
34460 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
34470 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
34480 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
34490 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
344a0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
344b0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
344c0 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ces..** If the 3
344d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
344e0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
344f0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
34500 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
34510 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
34520 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
34530 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
34540 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
34550 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
34560 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
34570 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
34580 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
34590 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
345a0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
345b0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
345c0 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
345d0 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
345e0 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
345f0 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
34600 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
34610 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
34620 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34630 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
34640 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  tion result..** 
34650 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
34660 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
34670 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
34680 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
34690 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
346a0 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
346b0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
346c0 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
346d0 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
346e0 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
346f0 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
34700 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
34710 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
34720 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
34730 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68  result..** If th
34740 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
34750 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
34760 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
34770 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c  rfaces or.** sql
34780 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
34790 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
347a0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
347b0 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c  STATIC, then SQL
347c0 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74  ite.** assumes t
347d0 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20  hat the text or 
347e0 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69  BLOB result is i
347f0 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  n constant space
34800 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a   and does not.**
34810 20 63 6f 70 79 20 74 68 65 20 69 74 20 6f 72 20   copy the it or 
34820 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
34830 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
34840 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
34850 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  t result..** If 
34860 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
34870 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
34880 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
34890 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
348a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
348b0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
348c0 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
348d0 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
348e0 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
348f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
34900 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
34910 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
34920 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
34930 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
34940 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
34950 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
34960 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
34970 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
34980 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
34990 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
349a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
349b0 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
349c0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
349d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
349e0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
349f0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
34a00 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71  eter.  The.** sq
34a10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
34a20 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
34a30 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
34a40 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
34a50 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
34a60 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
34a70 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
34a80 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
34a90 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
34aa0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
34ab0 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
34ac0 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
34ad0 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
34ae0 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20  ** A [protected 
34af0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
34b00 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
34b10 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
34b20 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
34b30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34b40 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
34b50 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
34b60 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
34b70 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
34b80 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
34b90 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
34ba0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
34bb0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
34bc0 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
34bd0 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
34be0 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
34bf0 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
34c00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34c10 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34c20 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
34c30 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
34c40 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
34c50 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
34c60 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
34c70 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
34c80 2a 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20 54 68  *.** {H16403} Th
34c90 65 20 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e  e default return
34ca0 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20   value from any 
34cb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
34cc0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  NULL..**.** {H16
34cd0 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  406} The [sqlite
34ce0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
34cf0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
34d00 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
34d10 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
34d20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
34d30 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 42 4c 4f  on C to be a BLO
34d40 42 20 74 68 61 74 20 69 73 20 4e 20 62 79 74 65  B that is N byte
34d50 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  s.**          in
34d60 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68   length and with
34d70 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64   content pointed
34d80 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20   to by V..**.** 
34d90 7b 48 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71  {H16409} The [sq
34da0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
34db0 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  ble(C,V)] interf
34dc0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
34dd0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
34de0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
34df0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
34e00 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
34e10 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
34e20 48 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c  H16412} The [sql
34e30 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34e40 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66  r(C,V,N)] interf
34e50 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
34e60 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
34e70 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63     value of func
34e80 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
34e90 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
34ea0 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
34eb0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52        [SQLITE_ER
34ec0 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 38  ROR] and a UTF-8
34ed0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63   error message c
34ee0 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20  opied from V up 
34ef0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
34f00 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79     first zero by
34f10 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79  te or until N by
34f20 74 65 73 20 61 72 65 20 72 65 61 64 20 69 66 20  tes are read if 
34f30 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a  N is positive..*
34f40 2a 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20 54 68  *.** {H16415} Th
34f50 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
34f60 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29  t_error16(C,V,N)
34f70 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
34f80 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
34f90 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
34fa0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
34fb0 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
34fc0 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
34fd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
34fe0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64  QLITE_ERROR] and
34ff0 20 61 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65   a UTF-16 native
35000 20 62 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f   byte order erro
35010 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
35020 20 20 20 20 20 20 63 6f 70 69 65 64 20 66 72 6f        copied fro
35030 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69  m V up to the fi
35040 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
35050 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62  tor or until N b
35060 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ytes.**         
35070 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69   are read if N i
35080 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a  s positive..**.*
35090 2a 20 7b 48 31 36 34 31 38 7d 20 54 68 65 20 5b  * {H16418} The [
350a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
350b0 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20  rror_toobig(C)] 
350c0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
350d0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
350e0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
350f0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43  f the function C
35100 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
35110 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
35120 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
35130 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20  [SQLITE_TOOBIG] 
35140 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61  and an appropria
35150 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
35160 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 31 7d  ..**.** {H16421}
35170 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
35180 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
35190 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
351a0 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
351b0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
351c0 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  lue of the funct
351d0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
351e0 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
351f0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
35200 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d       [SQLITE_NOM
35210 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  EM] and an appro
35220 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
35230 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  sage..**.** {H16
35240 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  424} The [sqlite
35250 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
35260 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 72 66  ode(C,E)] interf
35270 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
35280 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
35290 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
352a0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
352b0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
352c0 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e  th error code E.
352d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54 68 65  .**          The
352e0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
352f0 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  ext is unchanged
35300 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 37 7d  ..**.** {H16427}
35310 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
35320 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69  sult_int(C,V)] i
35330 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
35340 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
35350 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
35360 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
35370 65 20 74 68 65 20 33 32 2d 62 69 74 20 69 6e 74  e the 32-bit int
35380 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a  eger value V..**
35390 0a 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54 68 65  .** {H16430} The
353a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
353b0 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e 74  _int64(C,V)] int
353c0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
353d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
353e0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
353f0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
35400 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74 65 67  the 64-bit integ
35410 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  er value V..**.*
35420 2a 20 7b 48 31 36 34 33 33 7d 20 54 68 65 20 5b  * {H16433} The [
35430 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
35440 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63  ull(C)] interfac
35450 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
35460 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
35470 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
35480 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  on C to be NULL.
35490 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36 7d 20  .**.** {H16436} 
354a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
354b0 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
354c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
354d0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
354e0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
354f0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
35500 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 38 20  to be the UTF-8 
35510 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
35520 20 20 20 56 20 75 70 20 74 6f 20 74 68 65 20 66     V up to the f
35530 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69  irst zero if N i
35540 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20  s negative.**   
35550 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69         or the fi
35560 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56  rst N bytes of V
35570 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67   if N is non-neg
35580 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
35590 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  6439} The [sqlit
355a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
355b0 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
355c0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
355d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
355e0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
355f0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
35600 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
35610 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
35620 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20         string V 
35630 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
35640 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67  zero if N is neg
35650 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
35660 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e    or the first N
35670 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e   bytes of V if N
35680 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
35690 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 32 7d  ..**.** {H16442}
356a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
356b0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
356c0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
356d0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
356e0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
356f0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
35700 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
35710 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
35720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
35730 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20  ing V up to the 
35740 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20  first zero if N 
35750 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
35760 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66          or the f
35770 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 72 20  irst N bytes or 
35780 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
35790 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
357a0 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71 6c 69  16445} The [sqli
357b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
357c0 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  6le(C,V,N,D)] in
357d0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
357e0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
357f0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
35800 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
35810 20 74 68 65 20 55 54 46 2d 31 36 20 6c 69 74 74   the UTF-16 litt
35820 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  le-endian.**    
35830 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75        string V u
35840 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
35850 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61  ero if N is nega
35860 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
35870 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20   or the first N 
35880 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20  bytes of V if N 
35890 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
358a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38 7d 20  .**.** {H16448} 
358b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
358c0 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20  ult_value(C,V)] 
358d0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
358e0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
358f0 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
35900 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
35910 62 65 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  be the [unprotec
35920 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35930 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  e].**          o
35940 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  bject V..**.** {
35950 48 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c  H16451} The [sql
35960 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
35970 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72  blob(C,N)] inter
35980 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
35990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
359a0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
359b0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
359c0 20 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f 66 20   N-byte BLOB of 
359d0 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a  all zeros..**.**
359e0 20 7b 48 31 36 34 35 34 7d 20 54 68 65 20 5b 73   {H16454} The [s
359f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35a00 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ror()] and [sqli
35a10 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35a20 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
35a30 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b    interfaces mak
35a40 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69  e a copy of thei
35a50 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  r error message 
35a60 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a  strings before.*
35a70 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
35a80 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ning..**.** {H16
35a90 34 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 65  457} If the D de
35aa0 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
35ab0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
35ac0 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
35ad0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
35ae0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
35af0 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
35b00 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
35b10 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
35b20 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
35b30 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35b40 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
35b50 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
35b60 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
35b70 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
35b80 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e  N,D)] is the con
35b90 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54  stant [SQLITE_ST
35ba0 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ATIC].**        
35bb0 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75    then no destru
35bc0 63 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c  ctor is ever cal
35bd0 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74  led on the point
35be0 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a  er V and SQLite.
35bf0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 75  **          assu
35c00 6d 65 73 20 74 68 61 74 20 56 20 69 73 20 69 6d  mes that V is im
35c10 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b  mutable..**.** {
35c20 48 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 44  H16460} If the D
35c30 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61   destructor para
35c40 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
35c50 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
35c60 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
35c70 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
35c80 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
35c90 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  D)], [sqlite3_re
35ca0 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
35cb0 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
35cc0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
35cd0 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
35ce0 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  N,D)], or.**    
35cf0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
35d00 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
35d10 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20  ,V,N,D)] is the 
35d20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20  constant.**     
35d30 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41       [SQLITE_TRA
35d40 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65  NSIENT] then the
35d50 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65   interfaces make
35d60 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
35d70 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
35d80 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74  ent of V and ret
35d90 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a  ains the copy..*
35da0 2a 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20 49 66  *.** {H16463} If
35db0 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f   the D destructo
35dc0 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  r parameter to [
35dd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
35de0 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  lob(C,V,N,D)],.*
35df0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
35e00 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
35e10 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69  C,V,N,D)], [sqli
35e20 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
35e30 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  6(C,V,N,D)],.** 
35e40 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
35e50 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
35e60 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a  e(C,V,N,D)], or.
35e70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
35e80 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35e90 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16le(C,V,N,D)] i
35ea0 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68  s some value oth
35eb0 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
35ec0 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74      the constant
35ed0 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  s [SQLITE_STATIC
35ee0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52  ] and [SQLITE_TR
35ef0 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a  ANSIENT] then.**
35f00 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65            SQLite
35f10 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
35f20 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69   destructor D wi
35f30 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79  th V as its only
35f40 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
35f50 20 20 20 20 20 20 77 68 65 6e 20 69 74 20 68 61        when it ha
35f60 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
35f70 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a  the V value..*/.
35f80 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35f90 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
35fa0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
35fb0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
35fc0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
35fd0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35fe0 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
35ff0 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
36000 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
36010 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
36020 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36030 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
36040 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36050 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
36060 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36070 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
36080 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
36090 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
360a0 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
360b0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
360c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
360d0 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
360e0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
360f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36100 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
36110 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
36120 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36130 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
36140 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
36150 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36160 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
36170 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
36180 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
36190 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
361a0 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
361b0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
361c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
361d0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
361e0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
361f0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
36200 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
36210 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36220 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
36230 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36240 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
36250 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
36260 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36270 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
36280 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
36290 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
362a0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
362b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
362c0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
362d0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
362e0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
362f0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
36300 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
36310 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
36320 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
36330 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
36340 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
36350 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
36360 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
36370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
36380 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
36390 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48  ing Sequences {H
363a0 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a  16600} <S20300>.
363b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
363c0 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74  tions are used t
363d0 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74  o add new collat
363e0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f  ion sequences to
363f0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
36400 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
36410 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
36420 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
36430 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
36440 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69   the new collati
36450 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73  on sequence is s
36460 70 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54  pecified as a UT
36470 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
36480 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
36490 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
364a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
364b0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
364c0 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
364d0 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65  tring for sqlite
364e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
364f0 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63  on16(). In all c
36500 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  ases.** the name
36510 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68   is passed as th
36520 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
36530 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
36540 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  * The third argu
36550 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20  ment may be one 
36560 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
36570 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a   [SQLITE_UTF8],.
36580 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
36590 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  LE] or [SQLITE_U
365a0 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74  TF16BE], indicat
365b0 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65  ing that the use
365c0 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f  r-supplied.** ro
365d0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f  utine expects to
365e0 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74   be passed point
365f0 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65  ers to strings e
36600 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
36610 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  -8,.** UTF-16 li
36620 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle-endian, or 
36630 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
36640 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
36650 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72   The.** third ar
36660 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73  gument might als
36670 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  o be [SQLITE_UTF
36680 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69  16_ALIGNED] to i
36690 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a 2a 20  ndicate that.** 
366a0 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65  the routine expe
366b0 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  cts pointers to 
366c0 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67  16-bit word alig
366d0 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f  ned strings.** o
366e0 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  f UTF-16 in the 
366f0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
36700 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63 6f  r of the host co
36710 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20  mputer..**.** A 
36720 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75  pointer to the u
36730 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75  ser supplied rou
36740 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73  tine must be pas
36750 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68  sed as the fifth
36760 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49  .** argument.  I
36770 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
36780 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  is is the same a
36790 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  s deleting the c
367a0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
367b0 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51  ence (so that SQ
367c0 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c  Lite cannot call
367d0 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a   it anymore)..**
367e0 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61   Each time the a
367f0 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c  pplication suppl
36800 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ied function is 
36810 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70  invoked, it is p
36820 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20  assed.** as its 
36830 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
36840 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
36850 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  id* passed as th
36860 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
36870 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
36880 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36890 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
368a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
368b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65  ()..**.** The re
368c0 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74  maining argument
368d0 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  s to the applica
368e0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f  tion-supplied ro
368f0 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74  utine are two st
36900 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72  rings,.** each r
36910 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20  epresented by a 
36920 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70  (length, data) p
36930 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20  air and encoded 
36940 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a  in the encoding.
36950 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73  ** that was pass
36960 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
36970 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68  argument when th
36980 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  e collation sequ
36990 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69  ence was.** regi
369a0 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54  stered. {END}  T
369b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
369c0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
369d0 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a   routine should.
369e0 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69  ** return negati
369f0 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69  ve, zero or posi
36a00 74 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73  tive if the firs
36a10 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
36a20 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20   than,.** equal 
36a30 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
36a40 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73  han the second s
36a50 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52  tring. i.e. (STR
36a60 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e  ING1 - STRING2).
36a70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
36a80 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36a90 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
36aa0 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
36ab0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
36ac0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
36ad0 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20   takes an extra 
36ae0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
36af0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  s a destructor f
36b00 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  or.** the collat
36b10 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75  ion.  The destru
36b20 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77  ctor is called w
36b30 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
36b40 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65  n is.** destroye
36b50 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20  d and is passed 
36b60 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f  a copy of the fo
36b70 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76  urth parameter v
36b80 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  oid* pointer.** 
36b90 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
36ba0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
36bb0 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69  v2()..** Collati
36bc0 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65  ons are destroye
36bd0 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
36be0 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
36bf0 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  ter calls to the
36c00 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  .** collation cr
36c10 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
36c20 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61   or when the [da
36c30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36c40 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20  n] is closed.** 
36c50 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
36c60 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  lose()]..**.** I
36c70 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
36c80 20 7b 48 31 36 36 30 33 7d 20 41 20 73 75 63 63   {H16603} A succ
36c90 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74  essful call to t
36ca0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
36cb0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36cc0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
36cd0 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66  E,P,F,D)] interf
36ce0 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ace.**          
36cf0 72 65 67 69 73 74 65 72 73 20 66 75 6e 63 74 69  registers functi
36d00 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f 6d 70  on F as the comp
36d10 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  arison function 
36d20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20  used to.**      
36d30 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f      implement co
36d40 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74 68 65  llation X on the
36d50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36d60 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20  ction] B for.** 
36d70 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
36d80 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69  es having encodi
36d90 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ng E..**.** {H16
36da0 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65  604} SQLite unde
36db0 72 73 74 61 6e 64 73 20 74 68 65 20 58 20 70 61  rstands the X pa
36dc0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20  rameter to.**   
36dd0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
36de0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36df0 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
36e00 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  ] as a zero-term
36e10 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  inated.**       
36e20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20     UTF-8 string 
36e30 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 69 73  in which case is
36e40 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43   ignored for ASC
36e50 49 49 20 63 68 61 72 61 63 74 65 72 73 20 61 6e  II characters an
36e60 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
36e70 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72   significant for
36e80 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61   non-ASCII chara
36e90 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  cters..**.** {H1
36ea0 36 36 30 36 7d 20 53 75 63 63 65 73 73 69 76 65  6606} Successive
36eb0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
36ec0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36ed0 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
36ee0 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,D)].**         
36ef0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76   with the same v
36f00 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20  alues for B, X, 
36f10 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20  and E, override 
36f20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20  prior values.** 
36f30 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46           of P, F
36f40 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  , and D..**.** {
36f50 48 31 36 36 30 39 7d 20 49 66 20 74 68 65 20 64  H16609} If the d
36f60 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e 20 5b  estructor D in [
36f70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36f80 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
36f90 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20  E,P,F,D)].**    
36fa0 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c        is not NUL
36fb0 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63 61 6c  L then it is cal
36fc0 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  led with argumen
36fd0 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  t P when the.** 
36fe0 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
36ff0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
37000 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69 74 65  ropped by SQLite
37010 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 32 7d  ..**.** {H16612}
37020 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
37030 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64  ction is dropped
37040 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   when it is over
37050 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  loaded..**.** {H
37060 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69  16615} A collati
37070 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
37080 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68 65 20  ropped when the 
37090 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
370a0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
370b0 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
370c0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
370d0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 38  ]..**.** {H16618
370e0 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20 50 20  } The pointer P 
370f0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  in [sqlite3_crea
37100 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
37110 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a  B,X,E,P,F,D)].**
37120 20 20 20 20 20 20 20 20 20 20 69 73 20 70 61 73            is pas
37130 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
37140 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
37150 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 61 72  er to the compar
37160 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ison.**         
37170 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20   function F for 
37180 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
37190 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e  nvocations of F.
371a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31 7d 20  .**.** {H16621} 
371b0 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
371c0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
371d0 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20  ion(B,X,E,P,F)] 
371e0 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20  is exactly.**   
371f0 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
37200 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  as a call to [sq
37210 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37220 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74  lation_v2()] wit
37230 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  h.**          th
37240 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72  e same parameter
37250 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73  s and a NULL des
37260 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  tructor..**.** {
37270 48 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e  H16624} Followin
37280 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  g a [sqlite3_cre
37290 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
372a0 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a  (B,X,E,P,F,D)],.
372b0 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69  **          SQLi
372c0 74 65 20 75 73 65 73 20 74 68 65 20 63 6f 6d 70  te uses the comp
372d0 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  arison function 
372e0 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 20 63  F for all text c
372f0 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20  omparison.**    
37300 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f 6e 73        operations
37310 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
37320 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
37330 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73 20 74  on text values t
37340 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
37350 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  use the collatin
37360 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 64  g sequence named
37370 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32   X..**.** {H1662
37380 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
37390 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
373a0 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77  16(B,X,E,P,F)] w
373b0 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a  orks the same.**
373c0 20 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71            as [sq
373d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
373e0 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46  lation(B,X,E,P,F
373f0 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
37400 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
37410 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20  ollation name X 
37420 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73  is understood as
37430 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
37440 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
37450 20 20 20 20 20 20 20 20 20 69 6e 73 74 65 61 64           instead
37460 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a   of UTF-8..**.**
37470 20 7b 48 31 36 36 33 30 7d 20 57 68 65 6e 20 6d   {H16630} When m
37480 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 73  ultiple comparis
37490 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  on functions are
374a0 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 74   available for t
374b0 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
374c0 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65      collating se
374d0 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 63  quence, SQLite c
374e0 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 77  hooses the one w
374f0 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64 69  hose text encodi
37500 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ng.**          r
37510 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73  equires the leas
37520 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76  t amount of conv
37530 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20  ersion from the 
37540 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20  default.**      
37550 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e      text encodin
37560 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  g of the databas
37570 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
37580 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37590 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
375a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
375b0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
375c0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
375d0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
375e0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
375f0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
37600 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
37610 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37620 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
37630 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
37640 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
37650 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
37660 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
37670 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
37680 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
37690 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
376a0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
376b0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
376c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
376d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
376e0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
376f0 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
37700 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
37710 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
37720 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
37730 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
37740 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
37750 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
37760 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
37770 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
37780 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33  s {H16700} <S203
37790 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f  00>.**.** To avo
377a0 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
377b0 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
377c0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
377d0 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
377e0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
377f0 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
37800 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
37810 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
37820 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  h the.** [databa
37830 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
37840 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  o be called when
37850 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
37860 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
37870 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
37880 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  red..**.** If th
37890 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65  e function is re
378a0 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
378b0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  he sqlite3_colla
378c0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50  tion_needed() AP
378d0 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  I,.** then it is
378e0 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65   passed the name
378f0 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63  s of undefined c
37900 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
37910 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a  es as strings.**
37920 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
37930 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73  8. {H16703} If s
37940 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37950 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
37960 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  sed,.** the name
37970 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  s are passed as 
37980 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
37990 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
379a0 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  der..** A call t
379b0 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
379c0 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65  n replaces any e
379d0 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b  xisting callback
379e0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
379f0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
37a00 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
37a10 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
37a20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
37a30 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
37a40 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
37a50 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
37a60 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
37a70 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37a80 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
37a90 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
37aa0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
37ab0 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
37ac0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
37ad0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
37ae0 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
37af0 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
37b00 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
37b10 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
37b20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
37b30 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
37b40 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
37b50 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
37b60 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
37b70 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
37b80 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
37b90 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
37ba0 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a  on sequence..**.
37bb0 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
37bc0 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
37bd0 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
37be0 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
37bf0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
37c00 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37c10 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
37c20 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
37c30 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
37c40 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37c50 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  ation_v2()]..**.
37c60 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
37c70 2a 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20 41 20  *.** {H16702} A 
37c80 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
37c90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  to [sqlite3_coll
37ca0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50  ation_needed(D,P
37cb0 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,F)].**         
37cc0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   or [sqlite3_col
37cd0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
37ce0 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a  D,P,F)] causes.*
37cf0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
37d00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37d10 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65  ion] D to invoke
37d20 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68   callback F with
37d30 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20   first.**       
37d40 20 20 20 70 61 72 61 6d 65 74 65 72 20 50 20 77     parameter P w
37d50 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73  henever it needs
37d60 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75   a comparison fu
37d70 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20  nction for a.** 
37d80 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
37d90 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68 61 74  ng sequence that
37da0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f   it does not kno
37db0 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b  w about..**.** {
37dc0 48 31 36 37 30 34 7d 20 45 61 63 68 20 73 75 63  H16704} Each suc
37dd0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
37de0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
37df0 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a  on_needed()] or.
37e00 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
37e10 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
37e20 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72  eeded16()] overr
37e30 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  ides the callbac
37e40 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  k registered.** 
37e50 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20           on the 
37e60 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
37e70 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72  onnection] by pr
37e80 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74  ior calls to eit
37e90 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
37ea0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
37eb0 20 7b 48 31 36 37 30 36 7d 20 54 68 65 20 6e 61   {H16706} The na
37ec0 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73  me of the reques
37ed0 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ted collating fu
37ee0 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e  nction passed in
37ef0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
37f00 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
37f10 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
37f20 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68  s in UTF-8 if th
37f30 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
37f40 20 20 20 20 20 20 20 77 61 73 20 72 65 67 69 73         was regis
37f50 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  tered using [sql
37f60 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
37f70 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  eeded()] and.** 
37f80 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 20 55           is in U
37f90 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
37fa0 65 20 6f 72 64 65 72 20 69 66 20 74 68 65 20 63  e order if the c
37fb0 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20  allback was.**  
37fc0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
37fd0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
37fe0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37ff0 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
38000 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
38010 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
38020 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
38030 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
38040 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
38050 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
38060 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
38070 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
38080 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
38090 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
380a0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
380b0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
380c0 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
380d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
380e0 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
380f0 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
38100 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
38110 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
38120 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
38130 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
38140 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
38150 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
38160 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
38170 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
38180 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
38190 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
381a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
381b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
381c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
381d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
381e0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
381f0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
38200 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
38210 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
38220 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
38230 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
38240 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
38250 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
38260 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
38270 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
38280 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
38290 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
382a0 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
382b0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
382c0 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
382d0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
382e0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
382f0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
38300 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
38310 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
38320 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
38330 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
38340 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
38350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
38360 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
38370 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
38380 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
38390 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
383a0 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
383b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
383c0 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
383d0 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
383e0 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c   Time {H10530} <
383f0 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40410>.**.** Th
38400 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
38410 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  ) function cause
38420 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
38430 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
38440 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72  execution.** for
38450 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62   at least a numb
38460 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
38470 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
38480 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
38490 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72  *.** If the oper
384a0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
384b0 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
384c0 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
384d0 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  h.** millisecond
384e0 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
384f0 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
38500 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
38510 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61  up to.** the nea
38520 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65  rest second. The
38530 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
38540 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
38550 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71   actually.** req
38560 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20  uested from the 
38570 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
38580 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
38590 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
385a0 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72  ments this inter
385b0 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20  face by calling 
385c0 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20  the xSleep().** 
385d0 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
385e0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
385f0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  fs] object..**.*
38600 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
38610 0a 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54 68 65  .** {H10533} The
38620 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28   [sqlite3_sleep(
38630 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 6e  M)] interface in
38640 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65 70  vokes the xSleep
38650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 74  .**          met
38660 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
38670 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c  lt [sqlite3_vfs|
38680 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
38690 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 73  .**          sus
386a0 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20 6f  pend execution o
386b0 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  f the current th
386c0 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61 73  read for at leas
386d0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20  t.**          M 
386e0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a  milliseconds..**
386f0 0a 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54 68 65  .** {H10536} The
38700 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28   [sqlite3_sleep(
38710 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  M)] interface re
38720 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
38730 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
38740 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
38750 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 72  sleep actually r
38760 65 71 75 65 73 74 65 64 20 6f 66 20 74 68 65 20  equested of the 
38770 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20  operating.**    
38780 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77 68        system, wh
38790 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61 72  ich might be lar
387a0 67 65 72 20 74 68 61 6e 20 74 68 65 20 70 61 72  ger than the par
387b0 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74  ameter M..*/.int
387c0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
387d0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
387e0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
387f0 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
38800 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
38810 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30 30 30   {H10310} <S2000
38820 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73  0>.**.** If this
38830 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
38840 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
38850 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
38860 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
38870 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
38880 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
38890 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
388a0 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
388b0 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
388c0 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20   will be placed 
388d0 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  in that director
388e0 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72 69  y.  If this vari
388f0 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55