/ Hex Artifact Content
Login

Artifact 48e40b4115396ff7eaa1ade9fd90a59e1d8353a0:


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 34 20 32 30 30 39 2f 30  n,v 1.424 2009/0
05f0: 32 2f 30 33 20 31 38 3a 32 35 3a 31 33 20 64 72  2/03 18:25:13 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20  .** These no-op 
0750: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
0760: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65  in front of inte
0770: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74  rfaces to mark t
0780: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hose.** interfac
0790: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70  es as either dep
07a0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72  recated or exper
07b0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70  imental.  New ap
07c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
07d0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70  ould not use dep
07e0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65  recated intrface
07f0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
0800: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72  port for backwar
0810: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
0820: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
0830: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
0840: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
0850: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
0860: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
0870: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0880: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0890: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
08a0: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
08b0: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
08c0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
08d0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
08e0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
08f0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0900: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0910: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
0920: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
0930: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
0940: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
0950: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
0960: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
0970: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0980: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0990: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
09a0: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
09b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
09c0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
09d0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
09e0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
09f0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a00: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a10: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0a20: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0a30: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0a40: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0a50: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0a60: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0a70: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0a80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0a90: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0aa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0ab0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0ac0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0ad0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0ae0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31  n Numbers {H1001
0af0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
0b00: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0b10: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f  SION and SQLITE_
0b20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23  VERSION_NUMBER #
0b30: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68  defines in.** th
0b40: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65  e sqlite3.h file
0b50: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72   specify the ver
0b60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77  sion of SQLite w
0b70: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61  ith which.** tha
0b80: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73  t header file is
0b90: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a   associated..**.
0ba0: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22  ** The "version"
0bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20   of SQLite is a 
0bc0: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f  string of the fo
0bd0: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54  rm "X.Y.Z"..** T
0be0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61  he phrase "alpha
0bf0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68  " or "beta" migh
0c00: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66  t be appended af
0c10: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68  ter the Z..** Th
0c20: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a  e X value is maj
0c30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0c40: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51  r always 3 in SQ
0c50: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20  Lite3..** The X 
0c60: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0c70: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64  es when backward
0c80: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
0c90: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64  is.** broken and
0ca0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65   we intend to ne
0cb0: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61  ver break backwa
0cc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0cd0: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75  y..** The Y valu
0ce0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  e is the minor v
0cf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
0d00: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  d only changes w
0d10: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65  hen.** there are
0d20: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65   major feature e
0d30: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74  nhancements that
0d40: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f   are forwards co
0d50: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20  mpatible.** but 
0d60: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f  not backwards co
0d70: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  mpatible..** The
0d80: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20   Z value is the 
0d90: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61  release number a
0da0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  nd is incremente
0db0: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0dc0: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0dd0: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0de0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d  ever Y is increm
0df0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ented..**.** See
0e00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
0e10: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  libversion()] an
0e20: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  d [sqlite3_libve
0e30: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e  rsion_number()].
0e40: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
0e50: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31  S:.**.** {H10011
0e60: 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  } The SQLITE_VER
0e70: 53 49 4f 4e 20 23 64 65 66 69 6e 65 20 69 6e 20  SION #define in 
0e80: 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65  the sqlite3.h he
0e90: 61 64 65 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a  ader file shall.
0ea0: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 76 61 6c  **          eval
0eb0: 75 61 74 65 20 74 6f 20 61 20 73 74 72 69 6e 67  uate to a string
0ec0: 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73   literal that is
0ed0: 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73   the SQLite vers
0ee0: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
0ef0: 77 69 74 68 20 77 68 69 63 68 20 74 68 65 20 68  with which the h
0f00: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73  eader file is as
0f10: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  sociated..**.** 
0f20: 7b 48 31 30 30 31 34 7d 20 54 68 65 20 53 51 4c  {H10014} The SQL
0f30: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0f40: 45 52 20 23 64 65 66 69 6e 65 20 73 68 61 6c 6c  ER #define shall
0f50: 20 72 65 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69   resolve to an i
0f60: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
0f70: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75     with the valu
0f80: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0f90: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0fa0: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20   X, Y, and Z.** 
0fb0: 20 20 20 20 20 20 20 20 20 61 72 65 20 74 68 65           are the
0fc0: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20   major version, 
0fd0: 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61  minor version, a
0fe0: 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  nd release numbe
0ff0: 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  r..*/.#define SQ
1000: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1010: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
1020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1030: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d  ERSION_NUMBER  -
1040: 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d  -VERSION-NUMBER-
1050: 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  -../*.** CAPI3RE
1060: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
1070: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
1080: 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c 53 36  ers {H10020} <S6
1090: 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0100>.** KEYWORD
10a0: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
10b0: 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  on.**.** These f
10c0: 65 61 74 75 72 65 73 20 70 72 6f 76 69 64 65 20  eatures provide 
10d0: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
10e0: 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c  tion as the [SQL
10f0: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20  ITE_VERSION].** 
1100: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  and [SQLITE_VERS
1110: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66  ION_NUMBER] #def
1120: 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61 64  ines in the head
1130: 65 72 2c 20 62 75 74 20 61 72 65 20 61 73 73 6f  er, but are asso
1140: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
1150: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1160: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
1170: 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75 73   file.  Cautious
1180: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
1190: 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20  ht.** include a 
11a0: 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72 20 61  check in their a
11b0: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 76 65  pplication to ve
11c0: 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c  rify that.** sql
11d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
11e0: 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 73 20  number() always 
11f0: 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1200: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  e.** [SQLITE_VER
1210: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a  SION_NUMBER]..**
1220: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1230: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1240: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1250: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1260: 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74  on as is.** in t
1270: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
1280: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1290: 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e 63 74  tant.  The funct
12a0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 0a  ion is provided.
12b0: 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c  ** for use in DL
12c0: 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65  Ls since DLL use
12d0: 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f  rs usually do no
12e0: 74 20 68 61 76 65 20 64 69 72 65 63 74 20 61 63  t have direct ac
12f0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a  cess to string.*
1300: 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68  * constants with
1310: 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a  in the DLL..**.*
1320: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1330: 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54 68 65  .** {H10021} The
1340: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
1350: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69  sion_number()] i
1360: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72  nterface shall r
1370: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
1380: 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75    an integer equ
1390: 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45  al to [SQLITE_VE
13a0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a  RSION_NUMBER]..*
13b0: 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20 54 68  *.** {H10022} Th
13c0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69  e [sqlite3_versi
13d0: 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  on] string const
13e0: 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69  ant shall contai
13f0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
1400: 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 5b 53  e text of the [S
1410: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73  QLITE_VERSION] s
1420: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
1430: 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  0023} The [sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d  e3_libversion()]
1450: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
1460: 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
1470: 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20     a pointer to 
1480: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72  the [sqlite3_ver
1490: 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e  sion] string con
14a0: 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  stant..*/.SQLITE
14b0: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
14c0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
14d0: 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72  on[];.const char
14e0: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
14f0: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  sion(void);.int 
1500: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1510: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
1520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1530: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1540: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1550: 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 30 31  Threadsafe {H101
1560: 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a  00} <S60100>.**.
1570: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1580: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1590: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
15a0: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
15b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
15c0: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
15d0: 6f 72 20 6d 61 63 72 6f 20 31 20 6f 72 20 32 2c  or macro 1 or 2,
15e0: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
15f0: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1600: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1610: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1620: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1630: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1640: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1650: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1660: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1670: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1680: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1690: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
16a0: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
16b0: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
16c0: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
16d0: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
16e0: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
16f0: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1700: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1710: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1720: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1730: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1740: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1750: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1760: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1770: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1780: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  ** The default b
1790: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
17a0: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
17b0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
17c0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
17d0: 65 20 75 73 65 64 20 62 79 20 61 20 70 72 6f 67  e used by a prog
17e0: 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ram to make sure
17f0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72   that the.** ver
1800: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74  sion of SQLite t
1810: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e  hat it is linkin
1820: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f  g against was co
1830: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
1840: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69  he desired setti
1850: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ng of the [SQLIT
1860: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1870: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cro..**.** This 
1880: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
1890: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f  eports on the co
18a0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78  mpile-time mutex
18b0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74   setting.** of t
18c0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
18d0: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66  DSAFE] flag.  If
18e0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
18f0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49  led with.** SQLI
1900: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20  TE_THREADSAFE=1 
1910: 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65  then mutexes are
1920: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
1930: 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62  ult but.** can b
1940: 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69  e fully or parti
1950: 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73  ally disabled us
1960: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
1970: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
1980: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72  .** with the ver
1990: 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  bs [SQLITE_CONFI
19a0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c  G_SINGLETHREAD],
19b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
19c0: 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a  MULTITHREAD],.**
19d0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
19e0: 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20  IG_MUTEX].  The 
19f0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
1a00: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
1a10: 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20  ows.** only the 
1a20: 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d  default compile-
1a30: 74 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f  time setting, no
1a40: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
1a50: 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61  hanges.** to tha
1a60: 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  t setting..**.**
1a70: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
1a80: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
1a90: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
1aa0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1ab0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  on..**.** INVARI
1ac0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ANTS:.**.** {H10
1ad0: 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  101} The [sqlite
1ae0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1af0: 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72  function shall r
1b00: 65 74 75 72 6e 20 7a 65 72 6f 20 69 66 0a 2a 2a  eturn zero if.**
1b10: 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6f 6e            and on
1b20: 6c 79 20 69 66 20 53 51 4c 69 74 65 20 77 61 73  ly if SQLite was
1b30: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1b40: 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69  utexing code omi
1b50: 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  tted..**.** {H10
1b60: 31 30 32 7d 20 54 68 65 20 76 61 6c 75 65 20 72  102} The value r
1b70: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 5b  eturned by the [
1b80: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1b90: 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  fe()] function.*
1ba0: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
1bb0: 20 72 65 6d 61 69 6e 20 74 68 65 20 73 61 6d 65   remain the same
1bc0: 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f   across calls to
1bd0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
1be0: 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1bf0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76  te3_threadsafe(v
1c00: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
1c10: 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
1c20: 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c  Connection Handl
1c30: 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30 32  e {H12000} <S402
1c40: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1c50: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
1c60: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
1c70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
1c80: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
1c90: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
1ca0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
1cb0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1cc0: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
1cd0: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
1ce0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
1cf0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
1d00: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
1d10: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
1d20: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
1d30: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
1d40: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1d50: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1d60: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
1d70: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
1d80: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
1d90: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
1da0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
1db0: 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 75  ** is its destru
1dc0: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65  ctor.  There are
1dd0: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65   many other inte
1de0: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
1df0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1e00: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
1e10: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1e20: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
1e30: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1e40: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
1e50: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
1e60: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
1e70: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
1e80: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
1e90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
1ea0: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
1eb0: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
1ec0: 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b 48  Integer Types {H
1ed0: 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a  10200} <S10110>.
1ee0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
1ef0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
1f00: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
1f10: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
1f20: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
1f30: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
1f40: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
1f50: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
1f60: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
1f70: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
1f80: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
1f90: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
1fa0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
1fb0: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
1fc0: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
1fd0: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69  ferred type defi
1fe0: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nitions..** The 
1ff0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64  sqlite_int64 and
2000: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
2010: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74  ypes are support
2020: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
2030: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
2040: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e  y only..**.** IN
2050: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2060: 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b 73 71  {H10201} The [sq
2070: 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20  lite_int64] and 
2080: 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20  [sqlite3_int64] 
2090: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
20a0: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
20b0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
20c0: 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nteger..**.** {H
20d0: 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  10202} The [sqli
20e0: 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b  te_uint64] and [
20f0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d 20  sqlite3_uint64] 
2100: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
2110: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
2120: 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
2130: 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66   integer..*/.#if
2140: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2150: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
2160: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2170: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
2180: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2190: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
21a0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
21b0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
21c0: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
21d0: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
21e0: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
21f0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2200: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2210: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2220: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2230: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2240: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2250: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2260: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
2270: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2280: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
2290: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
22a0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
22b0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
22c0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
22d0: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
22e0: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
22f0: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2300: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2310: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2320: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2330: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2340: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2350: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
2360: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
2370: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
2380: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
2390: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
23a0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
23b0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
23c0: 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c  ction {H12010} <
23d0: 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a  S30100><S40200>.
23e0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
23f0: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2400: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2410: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2420: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
2430: 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65  s should [sqlite
2440: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2450: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2460: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2470: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2480: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2490: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
24a0: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
24b0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
24c0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
24d0: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
24e0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
24f0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20   object..** The 
2500: 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2510: 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  mt()] interface 
2520: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
2530: 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72  ocate all.** [pr
2540: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2550: 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  s] associated wi
2560: 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
2570: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64 65  onnection] if de
2580: 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61  sired..** Typica
2590: 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f  l code might loo
25a0: 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  k like this:.**.
25b0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
25c0: 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  pre>.** sqlite3_
25d0: 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20  stmt *pStmt;.** 
25e0: 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d 20  while( (pStmt = 
25f0: 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2600: 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a  t(db, 0))!=0 ){.
2610: 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c 69  ** &nbsp;   sqli
2620: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74  te3_finalize(pSt
2630: 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70  mt);.** }.** </p
2640: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
2650: 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  .**.** If [sqlit
2660: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69  e3_close()] is i
2670: 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74  nvoked while a t
2680: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
2690: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
26a0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
26b0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
26c0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ack..**.** INVAR
26d0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
26e0: 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 73 66  2011} A successf
26f0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2700: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68  te3_close(C)] sh
2710: 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 65 0a  all destroy the.
2720: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
2730: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2740: 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a  ] object C..**.*
2750: 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73 75 63  * {H12012} A suc
2760: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2770: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2780: 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  )] shall return 
2790: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a  SQLITE_OK..**.**
27a0: 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75 63 63   {H12013} A succ
27b0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
27c0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
27d0: 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 65 20  ] shall release 
27e0: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
27f0: 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 74 65  memory and syste
2800: 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f  m resources asso
2810: 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 61 74  ciated with [dat
2820: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2830: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e  ].**          C.
2840: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 7d 20  .**.** {H12014} 
2850: 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
2860: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20  e3_close(C)] on 
2870: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
2880: 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a  ection] C that.*
2890: 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 20 6f  *          has o
28a0: 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20  ne or more open 
28b0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28c0: 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c  ents] shall fail
28d0: 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
28e0: 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53    an [SQLITE_BUS
28f0: 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a  Y] error code..*
2900: 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 41 20  *.** {H12015} A 
2910: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2920: 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72 65  _close(C)] where
2930: 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   C is a NULL poi
2940: 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  nter shall.**   
2950: 20 20 20 20 20 20 20 62 65 20 61 20 68 61 72 6d         be a harm
2960: 6c 65 73 73 20 6e 6f 2d 6f 70 20 72 65 74 75 72  less no-op retur
2970: 6e 69 6e 67 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  ning SQLITE_OK..
2980: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 39 7d 20 57  **.** {H12019} W
2990: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  hen [sqlite3_clo
29a0: 73 65 28 43 29 5d 20 69 73 20 69 6e 76 6f 6b 65  se(C)] is invoke
29b0: 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65  d on a [database
29c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 0a 2a   connection] C.*
29d0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
29e0: 68 61 73 20 61 20 70 65 6e 64 69 6e 67 20 74 72  has a pending tr
29f0: 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 20 74  ansaction, the t
2a00: 72 61 6e 73 61 63 74 69 6f 6e 20 73 68 61 6c 6c  ransaction shall
2a10: 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   be.**          
2a20: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
2a30: 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
2a40: 2a 2a 0a 2a 2a 20 7b 41 31 32 30 31 36 7d 20 54  **.** {A12016} T
2a50: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74  he C parameter t
2a60: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
2a70: 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74  (C)] must be eit
2a80: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20  her a NULL.**   
2a90: 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 6f         pointer o
2aa0: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2ab0: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2ac0: 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  tained.**       
2ad0: 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33     from [sqlite3
2ae0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2af0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
2b00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2b10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2b20: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
2b30: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a  usly closed..*/.
2b40: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2b50: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2b60: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2b70: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2b80: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2b90: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2ba0: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2bb0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2bc0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2bd0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2be0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2bf0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2c00: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2c10: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2c20: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2c30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2c40: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2c50: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2c60: 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30  e {H12100} <S100
2c70: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
2c90: 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76  erface is a conv
2ca0: 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75  enient way of ru
2cb0: 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72  nning one or mor
2cc0: 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
2cd0: 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69  nts without havi
2ce0: 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f  ng to write a lo
2cf0: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68  t of C code.  Th
2d00: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a  e UTF-8 encoded.
2d10: 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
2d20: 73 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20  s are passed in 
2d30: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
2d40: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2d50: 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68  e3_exec()..** Th
2d60: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  e statements are
2d70: 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62   evaluated one b
2d80: 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68  y one until eith
2d90: 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a  er an error or.*
2da0: 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69  * an interrupt i
2db0: 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f  s encountered, o
2dc0: 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65  r until they are
2dd0: 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20   all done.  The 
2de0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  3rd parameter.**
2df0: 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20   is an optional 
2e00: 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73  callback that is
2e10: 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
2e20: 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e  r each row of an
2e30: 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c  y query.** resul
2e40: 74 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74  ts produced by t
2e50: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2e60: 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61  s.  The 5th para
2e70: 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72  meter tells wher
2e80: 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e  e.** to write an
2e90: 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73  y error messages
2ea0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f  ..**.** The erro
2eb0: 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64  r message passed
2ec0: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
2ed0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
2ee0: 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65  is held.** in me
2ef0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2f00: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2f10: 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64  oc()].  To avoid
2f20: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a   a memory leak,.
2f30: 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61  ** the calling a
2f40: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
2f50: 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  d call [sqlite3_
2f60: 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65  free()] on any e
2f70: 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
2f80: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68  returned through
2f90: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
2fa0: 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  er when it has f
2fb0: 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a  inished using.**
2fc0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
2fd0: 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ge..**.** If the
2fe0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
2ff0: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  n the 2nd parame
3000: 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  ter is NULL or a
3010: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a  n empty string.*
3020: 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f  * or a string co
3030: 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68  ntaining only wh
3040: 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d  itespace and com
3050: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53  ments, then no S
3060: 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  QL.** statements
3070: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
3080: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  nd the database 
3090: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a  is not changed..
30a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
30b0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
30c0: 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
30d0: 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a  d in terms of.**
30e0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30f0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3100: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
3110: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3120: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ()]..** The sqli
3130: 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69  te3_exec() routi
3140: 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20  ne does nothing 
3150: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
3160: 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64  that cannot be d
3170: 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  one.** by [sqlit
3180: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
3190: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
31a0: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
31b0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
31c0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
31d0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 31 7d 20 41  **.** {H12101} A
31e0: 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
31f0: 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
3200: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
3210: 45 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E)].**          
3220: 73 68 61 6c 6c 20 73 65 71 75 65 6e 74 69 61 6c  shall sequential
3230: 6c 79 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20  ly evaluate all 
3240: 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  of the UTF-8 enc
3250: 6f 64 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  oded,.**        
3260: 20 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61    semicolon-sepa
3270: 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
3280: 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
3290: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
32a0: 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 53          string S
32b0: 20 77 69 74 68 69 6e 20 74 68 65 20 63 6f 6e 74   within the cont
32c0: 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ext of the [data
32d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32e0: 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30   D..**.** {H1210
32f0: 32 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  2} If the S para
3300: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3310: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3320: 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a  )] is NULL then.
3330: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
3340: 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 69  actions of the i
3350: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62  nterface shall b
3360: 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 69 66  e the same as if
3370: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
3380: 20 53 20 70 61 72 61 6d 65 74 65 72 20 77 65 72   S parameter wer
3390: 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  e an empty strin
33a0: 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 34  g..**.** {H12104
33b0: 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
33c0: 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  ue of [sqlite3_e
33d0: 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20  xec()] shall be 
33e0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61  [SQLITE_OK] if a
33f0: 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ll.**          S
3400: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75  QL statements ru
3410: 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61  n successfully a
3420: 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  nd to completion
3430: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 35 7d  ..**.** {H12105}
3440: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
3450: 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78  e of [sqlite3_ex
3460: 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 61  ec()] shall be a
3470: 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
3480: 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d 7a 65            non-ze
3490: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
34a0: 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61 74 65  if any SQL state
34b0: 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  ment fails..**.*
34c0: 2a 20 7b 48 31 32 31 30 37 7d 20 49 66 20 6f 6e  * {H12107} If on
34d0: 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
34e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
34f0: 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74  handed to [sqlit
3500: 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20  e3_exec()].**   
3510: 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 72 65         return re
3520: 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20 33 72  sults and the 3r
3530: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
3540: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a  ot NULL, then.**
3550: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61            the ca
3560: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3570: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
3580: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 73   3rd parameter s
3590: 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20  hall be.**      
35a0: 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65      invoked once
35b0: 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66   for each row of
35c0: 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b   result..**.** {
35d0: 48 31 32 31 31 30 7d 20 49 66 20 74 68 65 20 63  H12110} If the c
35e0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
35f0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65  a non-zero value
3600: 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65   then [sqlite3_e
3610: 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  xec()].**       
3620: 20 20 20 73 68 61 6c 6c 20 61 62 6f 72 74 20 74     shall abort t
3630: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3640: 20 69 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79   it is currently
3650: 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20   evaluating,.** 
3660: 20 20 20 20 20 20 20 20 20 73 6b 69 70 20 61 6c           skip al
3670: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  l subsequent SQL
3680: 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64   statements, and
3690: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
36a0: 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ABORT]..**.** {H
36b0: 31 32 31 31 33 7d 20 54 68 65 20 5b 73 71 6c 69  12113} The [sqli
36c0: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74  te3_exec()] rout
36d0: 69 6e 65 20 73 68 61 6c 6c 20 70 61 73 73 20 69  ine shall pass i
36e0: 74 73 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  ts 4th parameter
36f0: 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20 20 20   through.**     
3700: 20 20 20 20 20 61 73 20 74 68 65 20 31 73 74 20       as the 1st 
3710: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
3720: 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
3730: 20 7b 48 31 32 31 31 36 7d 20 54 68 65 20 5b 73   {H12116} The [s
3740: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
3750: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74  outine shall set
3760: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3770: 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20  er of its.**    
3780: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74        callback t
3790: 6f 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  o be the number 
37a0: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
37b0: 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
37c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
37d0: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ult..**.** {H121
37e0: 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
37f0: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65  _exec()] routine
3800: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 33   shall set the 3
3810: 72 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  rd parameter of 
3820: 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
3830: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61  callback to be a
3840: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3850: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68  ers to strings h
3860: 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  olding the.**   
3870: 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 66 6f         values fo
3880: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e  r each column in
3890: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73   the current res
38a0: 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73 0a 2a  ult set row as.*
38b0: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69  *          obtai
38c0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
38d0: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
38e0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 32 7d  ..**.** {H12122}
38f0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
3900: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  ec()] routine sh
3910: 61 6c 6c 20 73 65 74 20 74 68 65 20 34 74 68 20  all set the 4th 
3920: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73  parameter of its
3930: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
3940: 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61  lback to be an a
3950: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3960: 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64   to strings hold
3970: 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ing the.**      
3980: 20 20 20 20 6e 61 6d 65 73 20 6f 66 20 72 65 73      names of res
3990: 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f  ult columns as o
39a0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
39b0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
39c0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  e()]..**.** {H12
39d0: 31 32 35 7d 20 49 66 20 74 68 65 20 33 72 64 20  125} If the 3rd 
39e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
39f0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
3a00: 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20   NULL then.**   
3a10: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
3a20: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 69  exec()] shall si
3a30: 6c 65 6e 74 6c 79 20 64 69 73 63 61 72 64 20 71  lently discard q
3a40: 75 65 72 79 20 72 65 73 75 6c 74 73 2e 0a 2a 2a  uery results..**
3a50: 0a 2a 2a 20 7b 48 31 32 31 33 31 7d 20 49 66 20  .** {H12131} If 
3a60: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
3a70: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72  while parsing or
3a80: 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20   evaluating any 
3a90: 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20  of the SQL.**   
3aa0: 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
3ab0: 73 20 69 6e 20 74 68 65 20 53 20 70 61 72 61 6d  s in the S param
3ac0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
3ad0: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3ae0: 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20  ] and if.**     
3af0: 20 20 20 20 20 74 68 65 20 45 20 70 61 72 61 6d       the E param
3b00: 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  eter is not NULL
3b10: 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  , then [sqlite3_
3b20: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 74  exec()] shall st
3b30: 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
3b40: 69 6e 20 2a 45 20 61 6e 20 61 70 70 72 6f 70 72  in *E an appropr
3b50: 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
3b60: 67 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ge written into 
3b70: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a  memory obtained.
3b80: 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
3b90: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
3ba0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ()]..**.** {H121
3bb0: 33 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  34} The [sqlite3
3bc0: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3bd0: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
3be0: 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66  set the value of
3bf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 45 20  .**          *E 
3c00: 74 6f 20 4e 55 4c 4c 20 69 66 20 45 20 69 73 20  to NULL if E is 
3c10: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65  not NULL and the
3c20: 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73  re are no errors
3c30: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 37 7d  ..**.** {H12137}
3c40: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
3c50: 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66  ec(D,S,C,A,E)] f
3c60: 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65  unction shall se
3c70: 74 20 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64  t the [error cod
3c80: 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  e].**          a
3c90: 6e 64 20 6d 65 73 73 61 67 65 20 61 63 63 65 73  nd message acces
3ca0: 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74  sible via [sqlit
3cb0: 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 0a  e3_errcode()], .
3cc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3cd0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
3ce0: 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20  rcode()],.**    
3cf0: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
3d00: 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73  rrmsg()], and [s
3d10: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
3d20: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33  )]..**.** {H1213
3d30: 38 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  8} If the S para
3d40: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3d50: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3d60: 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  )] is NULL or an
3d70: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6d 70  .**          emp
3d80: 74 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e  ty string or con
3d90: 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74  tains nothing ot
3da0: 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70  her than whitesp
3db0: 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a  ace, comments,.*
3dc0: 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 2f 6f  *          and/o
3dd0: 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68  r semicolons, th
3de0: 65 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73  en results of [s
3df0: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
3e00: 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
3e10: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
3e20: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
3e30: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3e40: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
3e50: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3e60: 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
3e70: 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 74 6f    shall reset to
3e80: 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72 72   indicate no err
3e90: 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ors..**.** ASSUM
3ea0: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
3eb0: 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73 74  12141} The first
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
3ed0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6d  qlite3_exec()] m
3ee0: 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 20  ust be an valid 
3ef0: 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 20  and open.**     
3f00: 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
3f10: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
3f20: 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 20 64  * {A12142} The d
3f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3f40: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63  on must not be c
3f50: 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 20  losed while.**  
3f60: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
3f70: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
3f80: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31  ing..**.** {A121
3f90: 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  43} The calling 
3fa0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
3fb0: 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  use [sqlite3_fre
3fc0: 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20  e()] to free.** 
3fd0: 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d           the mem
3fe0: 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67  ory that *errmsg
3ff0: 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
4000: 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72  g at once the er
4010: 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ror.**          
4020: 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c 6f  message is no lo
4030: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a  nger needed..**.
4040: 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 65 20  ** {A12145} The 
4050: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
4060: 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61  xt in the 2nd pa
4070: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
4080: 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20  te3_exec()].**  
4090: 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 65 6d          must rem
40a0: 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77 68  ain unchanged wh
40b0: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ile [sqlite3_exe
40c0: 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  c()] is running.
40d0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
40e0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
40f0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4120: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4130: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4150: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4160: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4170: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4180: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4190: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
41a0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
41b0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
41c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
41f0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4200: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4210: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4230: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4240: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4250: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4260: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31  Result Codes {H1
4270: 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  0210} <S10700>.*
4280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4290: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
42a0: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
42b0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
42c0: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
42d0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
42e0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
42f0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
4300: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
4310: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
4320: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
4330: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4340: 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72  cates success or
4350: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
4360: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
4370: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
4380: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
4390: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
43a0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
43b0: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
43c0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
43d0: 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  codes].*/.#defin
43e0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
43f0: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4400: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4410: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4420: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4440: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4450: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
4460: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
4470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4480: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
4490: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
44a0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
44b0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
44c0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
44d0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
44e0: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
44f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4500: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4510: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4520: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4530: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4550: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4560: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4570: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
4580: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4590: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
45a0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
45b0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
45c0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
45d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
45e0: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
45f0: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4600: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4610: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4620: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4630: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4640: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4660: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4670: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
4680: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
4690: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
46a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46b0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
46c0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
46d0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
46e0: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
46f0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4700: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4710: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4720: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4730: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4740: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4750: 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53    12   /* NOT US
4760: 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63  ED. Table or rec
4770: 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f  ord not found */
4780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4790: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
47a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
47b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
47c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
47d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
47f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4800: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4810: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4820: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
4830: 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55     15   /* NOT U
4840: 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f  SED. Database lo
4850: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f  ck protocol erro
4860: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4870: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20  ITE_EMPTY       
4880: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  16   /* Database
4890: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65   is empty */.#de
48a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45  fine SQLITE_SCHE
48b0: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20  MA      17   /* 
48c0: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  The database sch
48d0: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23  ema changed */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f  define SQLITE_TO
48f0: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f  OBIG      18   /
4900: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  * String or BLOB
4910: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69   exceeds size li
4920: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mit */.#define S
4930: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
4940: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20    19   /* Abort 
4950: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e  due to constrain
4960: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23  t violation */.#
4970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4980: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f  SMATCH    20   /
4990: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d  * Data type mism
49a0: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20  atch */.#define 
49b0: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20  SQLITE_MISUSE   
49c0: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61     21   /* Libra
49d0: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63  ry used incorrec
49e0: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tly */.#define S
49f0: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20  QLITE_NOLFS     
4a00: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f    22   /* Uses O
4a10: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73  S features not s
4a20: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74  upported on host
4a30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a40: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32  TE_AUTH        2
4a50: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61  3   /* Authoriza
4a60: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  tion denied */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f  define SQLITE_FO
4a80: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f  RMAT      24   /
4a90: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61  * Auxiliary data
4aa0: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f  base format erro
4ab0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4ac0: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20  ITE_RANGE       
4ad0: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61  25   /* 2nd para
4ae0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4af0: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e  _bind out of ran
4b00: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge */.#define SQ
4b10: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20  LITE_NOTADB     
4b20: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70   26   /* File op
4b30: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74  ened that is not
4b40: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
4b50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b60: 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31  TE_ROW         1
4b70: 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  00  /* sqlite3_s
4b80: 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65  tep() has anothe
4b90: 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23  r row ready */.#
4ba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f  define SQLITE_DO
4bb0: 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f  NE        101  /
4bc0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
4bd0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
4be0: 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e  ecuting */./* en
4bf0: 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  d-of-error-codes
4c00: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
4c10: 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65  REF: Extended Re
4c20: 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30 32  sult Codes {H102
4c30: 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20  20} <S10700>.** 
4c40: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c50: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4c60: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4c70: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4c80: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c90: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4ca0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4cb0: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4cc0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4cd0: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4ce0: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4cf0: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4d00: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4d10: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4d20: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4d30: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4d40: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4d50: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4d60: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4d70: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4d80: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d90: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4da0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4db0: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4dc0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4dd0: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4de0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4df0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4e00: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4e10: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4e20: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4e30: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4e40: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4e50: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4e60: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4e70: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4e80: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e90: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4ea0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4eb0: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4ec0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4ed0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4ee0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4ef0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4f00: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4f10: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4f20: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4f30: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4f40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f50: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4f60: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4f70: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4f80: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f90: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4fa0: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4fb0: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4fc0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4fd0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4fe0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4ff0: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
5000: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
5010: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
5020: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
5030: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
5040: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
5050: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
5060: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
5070: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a  exactly zero..**
5080: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
5090: 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d 20 54  **.** {H10223} T
50a0: 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
50b0: 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64   for an extended
50c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68 61   result code sha
50d0: 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  ll contains.**  
50e0: 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74 65          a relate
50f0: 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74  d primary result
5100: 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 69   code as a prefi
5110: 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 34  x..**.** {H10224
5120: 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74  } Primary result
5130: 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c   code names shal
5140: 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67  l contain a sing
5150: 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72  le "_" character
5160: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 35 7d  ..**.** {H10225}
5170: 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   Extended result
5180: 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c   code names shal
5190: 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72  l contain two or
51a0: 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63   more "_" charac
51b0: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ters..**.** {H10
51c0: 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 63  226} The numeric
51d0: 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 74   value of an ext
51e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
51f0: 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20  e shall contain 
5200: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
5210: 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66  numeric value of
5220: 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64 69   its correspondi
5230: 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c  ng primary resul
5240: 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20 20  t code in.**    
5250: 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74 20        its least 
5260: 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62 69  significant 8 bi
5270: 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ts..*/.#define S
5280: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
5290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
52a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
52b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
52d0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
52e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
52f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5300: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
5310: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5320: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
5330: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5340: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
5350: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5360: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
5390: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
53b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53c0: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
53d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
53e0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
53f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5400: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
5410: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5420: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
5430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5440: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5450: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5460: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5480: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5490: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54a0: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
54b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54c0: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
54d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
54e0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
54f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5500: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
5510: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5520: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5540: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5560: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5580: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5590: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55a0: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
55b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55c0: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
55d0: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
55e0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
55f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5600: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
5610: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5620: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
5630: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5640: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5650: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5660: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5670: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5680: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5690: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
56a0: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 0a 2f  RR | (17<<8))../
56b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
56c0: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
56d0: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48  en Operations {H
56e0: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20  10230} <H11120> 
56f0: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12700>.**.** T
5700: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
5710: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
5720: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
5730: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
5740: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
5750: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
5760: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
5770: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
5780: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
5790: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
57a0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
57b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
57c0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
57d0: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
57e0: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
57f0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
5800: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
5810: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5820: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
5830: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5840: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
5850: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
5860: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
5870: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
5880: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
5890: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
58a0: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
58b0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
58c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
58d0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
58e0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
58f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5900: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
5910: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
5920: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
5930: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
5940: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
5950: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5960: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
5970: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
5980: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5990: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
59a0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
59b0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
59c0: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  2000.#define SQL
59d0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
59e0: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
59f0: 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  4000.#define SQL
5a00: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
5a10: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a20: 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  8000.#define SQL
5a30: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
5a40: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
5a50: 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0000../*.** CAPI
5a60: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5a70: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
5a80: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
5a90: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5aa0: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
5ab0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
5ac0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
5ad0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
5ae0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
5af0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5b00: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5b10: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5b20: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5b30: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5b40: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5b50: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5b60: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5b70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5b80: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5b90: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
5ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5bb0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
5bc0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
5bd0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
5be0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
5bf0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5c00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5c10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5c20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5c30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5c40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5c50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5c60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5c70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5c80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5c90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
5ca0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5cb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
5cc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
5cd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
5ce0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
5cf0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5d00: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5d10: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5d20: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5d30: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5d40: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5d50: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5d60: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5d70: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5d80: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5d90: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
5da0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
5db0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
5dc0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
5dd0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
5de0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5df0: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
5e00: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5e10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e20: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
5e30: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
5e40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e50: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
5e60: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
5e70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e80: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
5e90: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
5ea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5eb0: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
5ec0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5ed0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ee0: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
5ef0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
5f00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f10: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
5f20: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
5f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f40: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
5f50: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
5f60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f70: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
5f80: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
5f90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5fa0: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
5fb0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
5fc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
5fd0: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
5fe0: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
5ff0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6000: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
6010: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
6020: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
6030: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
6040: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6050: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6060: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
6070: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
6080: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
6090: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
60a0: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
60b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
60c0: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
60d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
60e0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
60f0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
6100: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
6110: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
6120: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6130: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
6140: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
6150: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
6160: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6170: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
6180: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
6190: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
61a0: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
61b0: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
61c0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
61d0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
61e0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
61f0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6200: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6210: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
6220: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
6230: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6240: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6250: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
6260: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
6270: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6280: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
6290: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
62a0: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
62b0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
62c0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
62d0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
62e0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
62f0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
6300: 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54  ushed. The SQLIT
6310: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c  E_SYNC_NORMAL fl
6320: 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  ag means.** to u
6330: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
6340: 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65  ) semantics. The
6350: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6360: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20  L flag means.** 
6370: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
6380: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
6390: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
63a0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
63b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
63c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
63d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
63e0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
63f0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
6400: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6410: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
6420: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
6430: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
6440: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
6450: 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30  le {H11110} <S20
6460: 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  110>.**.** An [s
6470: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6480: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
6490: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
64a0: 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61  he OS.** interfa
64b0: 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76  ce layer.  Indiv
64c0: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
64d0: 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ce implementatio
64e0: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
64f0: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
6500: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
6510: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
6520: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
6530: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
6540: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
6550: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
6560: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6570: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6580: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
6590: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
65a0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
65b0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
65c0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
65d0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
65e0: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
65f0: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
6600: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
6610: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
6620: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
6630: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
6640: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
6650: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
6660: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6670: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
6680: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
6690: 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30 7d   Object {H11120}
66a0: 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S20110>.**.** 
66b0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
66c0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
66d0: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74  3_vfs] xOpen met
66e0: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
66f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
6700: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
6710: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
6720: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
6730: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
6740: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
6750: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
6760: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
6770: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
6780: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
6790: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
67a0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
67b0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
67c0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
67d0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
67e0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
67f0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
6800: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
6810: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
6820: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
6830: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
6840: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
6850: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
6860: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
6870: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
6880: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
6890: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
68a0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
68b0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
68c0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
68d0: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
68e0: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
68f0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
6900: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
6910: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
6920: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
6930: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
6940: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
6950: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
6960: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6970: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
6980: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6990: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
69a0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
69b0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
69c0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
69d0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
69e0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
69f0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
6a00: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
6a10: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6a20: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
6a30: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
6a40: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
6a50: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
6a60: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
6a70: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
6a80: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
6a90: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
6aa0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
6ab0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
6ac0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
6ad0: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
6ae0: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
6af0: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
6b00: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
6b10: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
6b20: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
6b30: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
6b40: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
6b50: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
6b60: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
6b70: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
6b80: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
6b90: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
6ba0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
6bb0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
6bc0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
6bd0: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
6be0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
6bf0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
6c00: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
6c10: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
6c20: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
6c30: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
6c40: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
6c50: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
6c60: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
6c70: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
6c80: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
6c90: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
6ca0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
6cb0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
6cc0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
6cd0: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
6ce0: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
6cf0: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
6d00: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
6d10: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
6d20: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
6d30: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
6d40: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
6d50: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
6d60: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
6d70: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
6d80: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
6d90: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
6da0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
6db0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
6dc0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
6dd0: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
6de0: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
6df0: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
6e00: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
6e10: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
6e20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
6e30: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
6e40: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
6e50: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
6e60: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
6e70: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
6e80: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
6e90: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
6ea0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
6eb0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
6ec0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
6ed0: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nflicts..**.** T
6ee0: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
6ef0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6f00: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
6f10: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
6f20: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
6f30: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
6f40: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
6f50: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
6f60: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
6f70: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
6f80: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
6f90: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
6fa0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
6fb0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6fc0: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
6fd0: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
6fe0: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
6ff0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
7000: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
7010: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
7020: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7030: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
7040: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7050: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
7060: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7070: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
7080: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7090: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
70a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
70c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
70e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
7100: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7110: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
7120: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7130: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
7140: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7150: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
7160: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
7170: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
7180: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
7190: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
71a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
71b0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
71c0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
71d0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
71e0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
71f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7200: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
7210: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
7220: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
7230: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
7240: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
7250: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
7260: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
7270: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
7280: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
7290: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
72a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
72b0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
72c0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
72d0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
72e0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
72f0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
7300: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
7310: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
7320: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
7330: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
7340: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
7350: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
7360: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
7370: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
7380: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
7390: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
73a0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
73b0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
73c0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
73d0: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
73e0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
73f0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
7400: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
7410: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
7420: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
7430: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
7440: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
7450: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
7460: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
7470: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
7480: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
7490: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
74a0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
74b0: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
74c0: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
74d0: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
74e0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
74f0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7500: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
7510: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
7520: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
7530: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
7540: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
7550: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
7560: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7570: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
7580: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
7590: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
75a0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
75b0: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
75c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
75d0: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
75e0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
75f0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
7600: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
7610: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
7620: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
7630: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
7640: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7650: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
7660: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
7670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
7680: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
7690: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
76a0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
76b0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
76c0: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
76d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
76e0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
76f0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
7700: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
7710: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
7720: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
7730: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7740: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
7750: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
7760: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
7770: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
7780: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
7790: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
77a0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64  _file*);.  /* Ad
77b0: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
77c0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
77d0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
77e0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
77f0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
7800: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
7810: 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d 20 3c  codes {H11310} <
7820: 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30800>.**.** Th
7830: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
7840: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
7850: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
7860: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
7870: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
7880: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7890: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
78a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
78b0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
78c0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
78d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
78e0: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
78f0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
7900: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
7910: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
7920: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
7930: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
7940: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
7950: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
7960: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
7970: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
7980: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7990: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
79a0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
79b0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
79c0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
79d0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
79e0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
79f0: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
7a00: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
7a10: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
7a20: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
7a30: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
7a40: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
7a50: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
7a60: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
7a70: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
7a80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7a90: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
7aa0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
7ab0: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
7ac0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
7ad0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7ae0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
7af0: 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  LE      3.#defin
7b00: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
7b10: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
7b20: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
7b30: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20  F: Mutex Handle 
7b40: 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31 33 30  {H17110} <S20130
7b50: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  >.**.** The mute
7b60: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
7b70: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
7b80: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
7b90: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
7ba0: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
7bb0: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
7bc0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
7bd0: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
7be0: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
7bf0: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
7c00: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
7c10: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
7c20: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
7c30: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
7c40: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
7c50: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
7c60: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
7c70: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
7c80: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
7c90: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7ca0: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
7cb0: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
7cc0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7cd0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b  terface Object {
7ce0: 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30 30 3e  H11140} <S20100>
7cf0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
7d00: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
7d10: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
7d20: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
7d30: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
7d40: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
7d50: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
7d60: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7d70: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
7d80: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
7d90: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
7da0: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
7db0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a  ile system"..**.
7dc0: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
7dd0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
7de0: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
7df0: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
7e00: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
7e10: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
7e20: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
7e30: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
7e40: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
7e50: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
7e60: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
7e70: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
7e80: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
7e90: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
7ea0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
7eb0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
7ec0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
7ed0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
7ee0: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
7ef0: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
7f00: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
7f10: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
7f20: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
7f30: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
7f40: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
7f50: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
7f60: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
7f70: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
7f80: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
7f90: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
7fa0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
7fb0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
7fc0: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
7fd0: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
7fe0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
7ff0: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
8000: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
8010: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
8020: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
8030: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
8040: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
8050: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
8060: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
8070: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
8080: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
8090: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
80a0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
80b0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
80c0: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
80d0: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
80e0: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
80f0: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
8100: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
8110: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
8120: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
8130: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
8140: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
8150: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
8160: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
8170: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
8180: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
8190: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
81a0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
81b0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
81c0: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
81d0: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
81e0: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
81f0: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
8200: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
8210: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
8220: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
8230: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
8240: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
8250: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
8260: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
8270: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
8280: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
8290: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
82a0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
82b0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
82c0: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
82d0: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
82e0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72  SQLite will guar
82f0: 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 7a  antee that the z
8300: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
8310: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
8320: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
8330: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
8340: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
8350: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
8360: 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72 74  ().  SQLite furt
8370: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
8380: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
8390: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
83a0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
83b0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
83c0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
83d0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
83e0: 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a 2a 20  us sentense,.** 
83f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8400: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
8410: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
8420: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
8430: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
8440: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
8450: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
8460: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
8470: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
8480: 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 69 73  eter is xOpen is
8490: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
84a0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
84b0: 73 74 20 69 6e 76 69 74 65 20 69 74 73 20 6f 77  st invite its ow
84c0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
84d0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
84e0: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
84f0: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
8500: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
8510: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
8520: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
8530: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
8540: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
8550: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8560: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
8570: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
8580: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
8590: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
85a0: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
85b0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
85c0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
85d0: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
85e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
85f0: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
8600: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
8610: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
8620: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
8630: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
8640: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
8650: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
8660: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
8670: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
8680: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
8690: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
86a0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
86b0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
86c0: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
86d0: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
86e0: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
86f0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73   SQLite will als
8700: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
8710: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
8720: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
8730: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
8740: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
8750: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
8760: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8770: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8780: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
8790: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
87a0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
87b0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
87c0: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
87d0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
87e0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
87f0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8800: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
8810: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
8820: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
8830: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
8840: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
8850: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
8860: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  /ul>.**.** The f
8870: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
8880: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
8890: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
88a0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
88b0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
88c0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
88d0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
88e0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
88f0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
8900: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
8910: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
8920: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
8930: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
8940: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
8950: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
8960: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
8970: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
8980: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
8990: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
89a0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
89b0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
89c0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
89d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
89e0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
89f0: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
8a00: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
8a10: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
8a20: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
8a30: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
8a40: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
8a50: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
8a60: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
8a70: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
8a80: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
8a90: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
8aa0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
8ab0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
8ac0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
8ad0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8ae0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8af0: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
8b00: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8b10: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
8b20: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
8b30: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8b40: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
8b50: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8b60: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
8b70: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
8b80: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8b90: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
8ba0: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
8bb0: 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73  or TEMP  databas
8bc0: 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64  es, journals and
8bd0: 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73   for subjournals
8be0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
8bf0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8c00: 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  VE] flag means t
8c10: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
8c20: 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20  e opened.** for 
8c30: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8c40: 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 73 20  .  This flag is 
8c50: 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65  set for all file
8c60: 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20  s except.** for 
8c70: 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
8c80: 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 74  e file..**.** At
8c90: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
8ca0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
8cb0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
8cc0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
8cd0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
8ce0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
8cf0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
8d00: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
8d10: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
8d20: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
8d30: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
8d40: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
8d50: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
8d60: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
8d70: 69 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  in..**.** The fl
8d80: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
8d90: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
8da0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
8db0: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
8dc0: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
8dd0: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
8de0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8df0: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
8e00: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
8e10: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
8e20: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
8e30: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
8e40: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
8e50: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
8e60: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
8e70: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
8e80: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
8e90: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
8ea0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
8eb0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
8ec0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
8ed0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
8ee0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
8ef0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
8f00: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
8f10: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
8f20: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
8f30: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
8f40: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
8f50: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
8f60: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
8f70: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
8f80: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
8f90: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
8fa0: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
8fb0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
8fc0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
8fd0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
8fe0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
8ff0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
9000: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
9010: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
9020: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
9030: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
9040: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
9050: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
9060: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
9070: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
9080: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
9090: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c   are not strictl
90a0: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20  y a part of the 
90b0: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20  filesystem, but 
90c0: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c  they are.** incl
90d0: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20  uded in the VFS 
90e0: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f  structure for co
90f0: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54  mpleteness..** T
9100: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
9110: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70   function attemp
9120: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79  ts to return nBy
9130: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  tes bytes.** of 
9140: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e  good-quality ran
9150: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75  domness into zOu
9160: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  t.  The return v
9170: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61  alue is.** the a
9180: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  ctual number of 
9190: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
91a0: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a  ess obtained..**
91b0: 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   The xSleep() me
91c0: 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20  thod causes the 
91d0: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74  calling thread t
91e0: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a  o sleep for at.*
91f0: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  * least the numb
9200: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e  er of microsecon
9210: 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78  ds given.  The x
9220: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
9230: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
9240: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
9250: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
9260: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
9270: 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66  e..**.*/.typedef
9280: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
9290: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
92a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
92b0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
92c0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
92d0: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
92e0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  rsion number */.
92f0: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
9300: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
9310: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
9320: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
9330: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
9340: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
9350: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
9360: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
9370: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
9380: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
9390: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
93a0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
93b0: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
93c0: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
93d0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
93e0: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
93f0: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
9400: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
9410: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
9420: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
9430: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
9440: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
9450: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
9460: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
9470: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
9480: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
9490: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
94a0: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
94b0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
94c0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
94d0: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
94e0: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
94f0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
9500: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
9510: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
9520: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
9530: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
9540: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
9550: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
9560: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
9570: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
9580: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
9590: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
95a0: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
95b0: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
95c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
95d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
95e0: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28  Msg);.  void (*(
95f0: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
9600: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
9610: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
9620: 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64  ))(void);.  void
9630: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
9640: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
9650: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
9660: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
9670: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
9680: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
9690: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
96a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
96b0: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
96c0: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
96d0: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
96e0: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69  *, double*);.  i
96f0: 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72  nt (*xGetLastErr
9700: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
9710: 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a  , int, char *);.
9720: 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    /* New fields 
9730: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
9740: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
9750: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
9760: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
9770: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
9780: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
9790: 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  s. */.};../*.** 
97a0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
97b0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
97c0: 56 46 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 31  VFS method {H111
97d0: 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a  90} <H11140>.**.
97e0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
97f0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
9800: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
9810: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
9820: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
9830: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
9840: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
9850: 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64  t. {END}  They d
9860: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
9870: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
9880: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
9890: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
98a0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
98b0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
98c0: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
98d0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
98e0: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
98f0: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
9900: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
9910: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
9920: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
9930: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
9940: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
9950: 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  e is both readab
9960: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e  le and writable.
9970: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
9980: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
9990: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
99a0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
99b0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
99c0: 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69  adable..*/.#defi
99d0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
99e0: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
99f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
9a00: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23  SS_READWRITE 1.#
9a10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
9a20: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
9a30: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9a40: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
9a50: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20   SQLite Library 
9a60: 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30  {H10130} <S20000
9a70: 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S30100>.**.** 
9a80: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9a90: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9aa0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
9ab0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
9ac0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
9ad0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
9ae0: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
9af0: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
9b00: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
9b10: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
9b20: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
9b30: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
9b40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9b50: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
9b60: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
9b70: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
9b80: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
9b90: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
9ba0: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
9bb0: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
9bc0: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
9bd0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
9be0: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
9bf0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
9c00: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
9c10: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
9c20: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9c30: 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63  .  Only an effec
9c40: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
9c50: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9c60: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
9c70: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
9c80: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
9c90: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
9ca0: 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  o-ops..**.** Amo
9cb0: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
9cc0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9cd0: 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f  ize() shall invo
9ce0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
9cf0: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
9d00: 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75  rly, sqlite3_shu
9d10: 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c  tdown().** shall
9d20: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
9d30: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
9d40: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9d50: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9d60: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
9d70: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
9d80: 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20  .** If for some 
9d90: 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  reason, sqlite3_
9da0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
9db0: 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61  unable to initia
9dc0: 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72  lize.** the libr
9dd0: 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20  ary (perhaps it 
9de0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
9df0: 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72  ocate a needed r
9e00: 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20  esource such.** 
9e10: 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72  as a mutex) it r
9e20: 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72  eturns an [error
9e30: 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61   code] other tha
9e40: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  n [SQLITE_OK]..*
9e50: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
9e60: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
9e70: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
9e80: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
9e90: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
9ea0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
9eb0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
9ec0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
9ed0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
9ee0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
9ef0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
9f00: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
9f10: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
9f20: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
9f30: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9f40: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
9f50: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
9f60: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
9f70: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
9f80: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
9f90: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
9fa0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
9fb0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
9fc0: 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76 65 72  lready.  However
9fd0: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
9fe0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
9ff0: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
a000: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
a010: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
a020: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
a030: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
a040: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a050: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
a060: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
a070: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
a080: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a090: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
a0a0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
a0b0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
a0c0: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
a0d0: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
a0e0: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
a0f0: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
a100: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
a110: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
a120: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
a130: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
a140: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
a150: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a160: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
a170: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
a180: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
a190: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
a1a0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
a1b0: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
a1c0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
a1d0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
a1e0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
a1f0: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
a200: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
a210: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
a220: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
a230: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
a240: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
a250: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
a260: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
a270: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
a280: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
a290: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
a2a0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
a2b0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
a2c0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
a2d0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
a2e0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
a2f0: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
a300: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
a310: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
a320: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
a330: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
a340: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
a350: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
a360: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
a370: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
a380: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
a390: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
a3a0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
a3b0: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
a3c0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
a3d0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
a3e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
a3f0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
a400: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
a410: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
a420: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a430: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
a440: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
a450: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
a460: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
a470: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
a480: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
a490: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
a4a0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
a4b0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
a4c0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
a4d0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
a4e0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
a4f0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
a500: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a510: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
a520: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a530: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
a540: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a550: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
a560: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
a570: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
a580: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
a590: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
a5a0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75  s compiled for u
a5b0: 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72  nix, windows, or
a5c0: 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62   os/2..** When b
a5d0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
a5e0: 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20  latforms (using 
a5f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
a600: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
a610: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
a620: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
a630: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
a640: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
a650: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
a660: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
a670: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
a680: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
a690: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
a6a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a6b0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
a6c0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
a6d0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
a6e0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
a6f0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
a700: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
a710: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
a720: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
a730: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
a740: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
a750: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
a760: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
a770: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
a780: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
a790: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
a7a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
a7b0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
a7c0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48  QLite Library {H
a7d0: 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c  14100} <S20000><
a7e0: 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S30200>.** EXPER
a7f0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
a800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
a810: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
a820: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
a830: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
a840: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
a850: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
a860: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
a870: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
a880: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
a890: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
a8a0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
a8b0: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
a8c0: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
a8d0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
a8e0: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
a8f0: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
a900: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
a910: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
a920: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
a930: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
a940: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
a950: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
a960: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
a970: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
a980: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
a990: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
a9a0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
a9b0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
a9c0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
a9d0: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
a9e0: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
a9f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
aa00: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
aa10: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
aa20: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
aa30: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
aa40: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
aa50: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
aa60: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
aa70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
aa80: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
aa90: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
aaa0: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
aab0: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
aac0: 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  hat sqlite3_conf
aad0: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
aae0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
aaf0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
ab00: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
ab10: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
ab20: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ab30: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
ab40: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
ab50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ab60: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
ab70: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
ab80: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
ab90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
aba0: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
abb0: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
abc0: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
abd0: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
abe0: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
abf0: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
ac00: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
ac10: 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
ac20: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
ac30: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
ac40: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
ac50: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ac60: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63  ..**.** When a c
ac70: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ac80: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
ac90: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
aca0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
acb0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69  ..** If the opti
acc0: 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
acd0: 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
ace0: 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
acf0: 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
ad00: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
ad10: 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
ad20: 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
ad30: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
ad40: 2a 20 7b 48 31 34 31 30 33 7d 20 41 20 73 75 63  * {H14103} A suc
ad50: 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
ad60: 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63  on of [sqlite3_c
ad70: 6f 6e 66 69 67 28 29 5d 20 73 68 61 6c 6c 20 72  onfig()] shall r
ad80: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
ad90: 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a    [SQLITE_OK]..*
ada0: 2a 0a 2a 2a 20 7b 48 31 34 31 30 36 7d 20 54 68  *.** {H14106} Th
adb0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
adc0: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  g()] interface s
add0: 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  hall return [SQL
ade0: 49 54 45 5f 4d 49 53 55 53 45 5d 0a 2a 2a 20 20  ITE_MISUSE].**  
adf0: 20 20 20 20 20 20 20 20 69 66 20 69 74 20 69 73          if it is
ae00: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 62 65 74 77   invoked in betw
ae10: 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  een calls to [sq
ae20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ae30: 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ()] and.**      
ae40: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 68 75      [sqlite3_shu
ae50: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  tdown()]..**.** 
ae60: 7b 48 31 34 31 32 30 7d 20 41 20 73 75 63 63 65  {H14120} A succe
ae70: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
ae80: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
ae90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
aea0: 4e 47 4c 45 54 48 52 45 41 44 5d 29 0a 2a 2a 20  NGLETHREAD]).** 
aeb0: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73           shall s
aec0: 65 74 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  et the default [
aed0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
aee0: 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
aef0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 33 7d  ..**.** {H14123}
af00: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
af10: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
af20: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
af30: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
af40: 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D]).**          
af50: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 64 65  shall set the de
af60: 66 61 75 6c 74 20 5b 74 68 72 65 61 64 69 6e 67  fault [threading
af70: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
af80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  thread..**.** {H
af90: 31 34 31 32 36 7d 20 41 20 73 75 63 63 65 73 73  14126} A success
afa0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
afb0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
afc0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
afd0: 41 4c 49 5a 45 44 5d 29 0a 2a 2a 20 20 20 20 20  ALIZED]).**     
afe0: 20 20 20 20 20 73 68 61 6c 6c 20 73 65 74 20 74       shall set t
aff0: 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68 72 65  he default [thre
b000: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
b010: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  erialized..**.**
b020: 20 7b 48 31 34 31 32 39 7d 20 41 20 73 75 63 63   {H14129} A succ
b030: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
b040: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
b050: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
b060: 55 54 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20  UTEX],X).**     
b070: 20 20 20 20 20 77 68 65 72 65 20 58 20 69 73 20       where X is 
b080: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
b090: 69 6e 69 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c  initialized [sql
b0a0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
b0b0: 64 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ds].**          
b0c0: 6f 62 6a 65 63 74 20 73 68 61 6c 6c 20 63 61 75  object shall cau
b0d0: 73 65 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  se all subsequen
b0e0: 74 20 6d 75 74 65 78 20 6f 70 65 72 61 74 69 6f  t mutex operatio
b0f0: 6e 73 20 70 65 72 66 6f 72 6d 65 64 0a 2a 2a 20  ns performed.** 
b100: 20 20 20 20 20 20 20 20 20 62 79 20 53 51 4c 69           by SQLi
b110: 74 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 75  te to use the mu
b120: 74 65 78 20 6d 65 74 68 6f 64 73 20 74 68 61 74  tex methods that
b130: 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 69 6e   were present in
b140: 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64   X.**          d
b150: 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 74  uring the call t
b160: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b170: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  g()]..**.** {H14
b180: 31 33 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  132} A successfu
b190: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
b1a0: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b1b0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
b1c0: 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 20 20  EX],X).**       
b1d0: 20 20 20 77 68 65 72 65 20 58 20 69 73 20 61 20     where X is a 
b1e0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73  pointer to an [s
b1f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
b200: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 0a 2a 2a  hods] object .**
b210: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
b220: 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 63 6f  overwrite the co
b230: 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65  ntent of [sqlite
b240: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
b250: 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20   object.**      
b260: 20 20 20 20 77 69 74 68 20 74 68 65 20 6d 75 74      with the mut
b270: 65 78 20 6d 65 74 68 6f 64 73 20 63 75 72 72 65  ex methods curre
b280: 6e 74 6c 79 20 69 6e 20 75 73 65 20 62 79 20 53  ntly in use by S
b290: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  QLite..**.** {H1
b2a0: 34 31 33 35 7d 20 41 20 73 75 63 63 65 73 73 66  4135} A successf
b2b0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
b2c0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
b2d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
b2e0: 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20 20 20 20 20  C],M).**        
b2f0: 20 20 77 68 65 72 65 20 4d 20 69 73 20 61 20 70    where M is a p
b300: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 69  ointer to an ini
b310: 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c 69 74 65  tialized [sqlite
b320: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
b330: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63  *          objec
b340: 74 20 73 68 61 6c 6c 20 63 61 75 73 65 20 61 6c  t shall cause al
b350: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6d 65 6d  l subsequent mem
b360: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ory allocation o
b370: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 20 20 20  perations.**    
b380: 20 20 20 20 20 20 70 65 72 66 6f 72 6d 65 64 20        performed 
b390: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  by SQLite to use
b3a0: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 74 68 61   the methods tha
b3b0: 74 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 69  t were present i
b3c0: 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d  n .**          M
b3d0: 20 64 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c   during the call
b3e0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
b3f0: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  fig()]..**.** {H
b400: 31 34 31 33 38 7d 20 41 20 73 75 63 63 65 73 73  14138} A success
b410: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
b420: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
b430: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
b440: 41 4c 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20  ALLOC],M).**    
b450: 20 20 20 20 20 20 77 68 65 72 65 20 4d 20 69 73        where M is
b460: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
b470: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
b480: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 73 68  thods] object sh
b490: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
b4a0: 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 63 6f  overwrite the co
b4b0: 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65  ntent of [sqlite
b4c0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 6f  3_mem_methods] o
b4d0: 62 6a 65 63 74 20 77 69 74 68 20 0a 2a 2a 20 20  bject with .**  
b4e0: 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d 6f          the memo
b4f0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6d 65  ry allocation me
b500: 74 68 6f 64 73 20 63 75 72 72 65 6e 74 6c 79 20  thods currently 
b510: 69 6e 20 75 73 65 20 62 79 0a 2a 2a 20 20 20 20  in use by.**    
b520: 20 20 20 20 20 20 53 51 4c 69 74 65 2e 0a 2a 2a        SQLite..**
b530: 0a 2a 2a 20 7b 48 31 34 31 34 31 7d 20 41 20 73  .** {H14141} A s
b540: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
b550: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b560: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
b570: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 31 29 0a  G_MEMSTATUS],1).
b580: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
b590: 6c 20 65 6e 61 62 6c 65 20 74 68 65 20 6d 65 6d  l enable the mem
b5a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
b5b0: 74 61 74 75 73 20 63 6f 6c 6c 65 63 74 69 6f 6e  tatus collection
b5c0: 20 6c 6f 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48   logic..**.** {H
b5d0: 31 34 31 34 34 7d 20 41 20 73 75 63 63 65 73 73  14144} A success
b5e0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
b5f0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
b600: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
b610: 54 41 54 55 53 5d 2c 30 29 0a 2a 2a 20 20 20 20  TATUS],0).**    
b620: 20 20 20 20 20 20 73 68 61 6c 6c 20 64 69 73 61        shall disa
b630: 62 6c 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ble the memory a
b640: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73  llocation status
b650: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69   collection logi
b660: 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 37  c..**.** {H14147
b670: 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  } The memory all
b680: 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63  ocation status c
b690: 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 20  ollection logic 
b6a0: 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20  shall be.**     
b6b0: 20 20 20 20 20 65 6e 61 62 6c 65 64 20 62 79 20       enabled by 
b6c0: 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b  default..**.** {
b6d0: 48 31 34 31 35 30 7d 20 41 20 73 75 63 63 65 73  H14150} A succes
b6e0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
b6f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
b700: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
b710: 41 54 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20  ATCH],S,Z,N).** 
b720: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a           where Z
b730: 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e   and N are non-n
b740: 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73  egative integers
b750: 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20   and .**        
b760: 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72    S is a pointer
b770: 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d   to an aligned m
b780: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74  emory buffer not
b790: 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20   less than.**   
b7a0: 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73         Z*N bytes
b7b0: 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63   in size shall c
b7c0: 61 75 73 65 20 53 20 74 6f 20 62 65 20 75 73 65  ause S to be use
b7d0: 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
b7e0: 20 20 20 20 20 5b 73 63 72 61 74 63 68 20 6d 65       [scratch me
b7f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
b800: 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73 20 4e  for as many as N
b810: 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73 0a 2a   simulataneous.*
b820: 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63  *          alloc
b830: 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66 20 73  ations each of s
b840: 69 7a 65 20 28 5a 20 26 20 7e 37 29 2e 0a 2a 2a  ize (Z & ~7)..**
b850: 0a 2a 2a 20 7b 48 31 34 31 35 33 7d 20 41 20 73  .** {H14153} A s
b860: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
b870: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b880: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
b890: 47 5f 53 43 52 41 54 43 48 5d 2c 53 2c 5a 2c 4e  G_SCRATCH],S,Z,N
b8a0: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  ).**          wh
b8b0: 65 72 65 20 53 20 69 73 20 61 20 4e 55 4c 4c 20  ere S is a NULL 
b8c0: 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 64 69  pointer shall di
b8d0: 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20 20 20  sable the.**    
b8e0: 20 20 20 20 20 20 5b 73 63 72 61 74 63 68 20 6d        [scratch m
b8f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
b900: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 36 7d  ..**.** {H14156}
b910: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
b920: 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ll to.**        
b930: 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69    [sqlite3_confi
b940: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
b950: 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 53 2c 5a  G_PAGECACHE],S,Z
b960: 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ,N).**          
b970: 77 68 65 72 65 20 5a 20 61 6e 64 20 4e 20 61 72  where Z and N ar
b980: 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 69  e non-negative i
b990: 6e 74 65 67 65 72 73 20 61 6e 64 20 0a 2a 2a 20  ntegers and .** 
b9a0: 20 20 20 20 20 20 20 20 20 53 20 69 73 20 61 20           S is a 
b9b0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 6c  pointer to an al
b9c0: 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
b9d0: 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 74 68 61  fer not less tha
b9e0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5a 2a  n.**          Z*
b9f0: 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
ba00: 73 68 61 6c 6c 20 63 61 75 73 65 20 53 20 74 6f  shall cause S to
ba10: 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65 0a   be used by the.
ba20: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 61 67  **          [pag
ba30: 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ecache memory al
ba40: 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 61 73 20  locator] for as 
ba50: 6d 61 6e 79 20 61 73 20 4e 20 73 69 6d 75 6c 61  many as N simula
ba60: 74 61 6e 65 6f 75 73 0a 2a 2a 20 20 20 20 20 20  taneous.**      
ba70: 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20      allocations 
ba80: 65 61 63 68 20 6f 66 20 73 69 7a 65 20 28 5a 20  each of size (Z 
ba90: 26 20 7e 37 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  & ~7)..**.** {H1
baa0: 34 31 35 39 7d 20 41 20 73 75 63 63 65 73 73 66  4159} A successf
bab0: 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20  ul call to.**   
bac0: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
bad0: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
bae0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
baf0: 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20  ],S,Z,N).**     
bb00: 20 20 20 20 20 77 68 65 72 65 20 53 20 69 73 20       where S is 
bb10: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  a NULL pointer s
bb20: 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65  hall disable the
bb30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 61  .**          [pa
bb40: 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  gecache memory a
bb50: 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a  llocator]..**.**
bb60: 20 7b 48 31 34 31 36 32 7d 20 41 20 73 75 63 63   {H14162} A succ
bb70: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
bb80: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
bb90: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
bba0: 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20  EAP],H,Z,N).**  
bbb0: 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a 20          where Z 
bbc0: 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65  and N are non-ne
bbd0: 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 20  gative integers 
bbe0: 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  and .**         
bbf0: 20 48 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20   H is a pointer 
bc00: 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d 65  to an aligned me
bc10: 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 20  mory buffer not 
bc20: 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20  less than.**    
bc30: 20 20 20 20 20 20 5a 20 62 79 74 65 73 20 69 6e        Z bytes in
bc40: 20 73 69 7a 65 20 73 68 61 6c 6c 20 65 6e 61 62   size shall enab
bc50: 6c 65 20 74 68 65 20 5b 6d 65 6d 73 79 73 35 5d  le the [memsys5]
bc60: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
bc70: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  r.**          an
bc80: 64 20 63 61 75 73 65 20 69 74 20 74 6f 20 75 73  d cause it to us
bc90: 65 20 62 75 66 66 65 72 20 53 20 61 73 20 69 74  e buffer S as it
bca0: 73 20 6d 65 6d 6f 72 79 20 73 6f 75 72 63 65 20  s memory source 
bcb0: 61 6e 64 20 74 6f 20 75 73 65 0a 2a 2a 20 20 20  and to use.**   
bcc0: 20 20 20 20 20 20 20 61 20 6d 69 6e 69 6d 75 6d         a minimum
bcd0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
bce0: 20 6f 66 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   of N..**.** {H1
bcf0: 34 31 36 35 7d 20 41 20 73 75 63 63 65 73 73 66  4165} A successf
bd00: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
bd10: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
bd20: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
bd30: 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20  ,H,Z,N).**      
bd40: 20 20 20 20 77 68 65 72 65 20 48 20 69 73 20 61      where H is a
bd50: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73 68   NULL pointer sh
bd60: 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65 0a  all disable the.
bd70: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 6d 65 6d  **          [mem
bd80: 73 79 73 35 5d 20 6d 65 6d 6f 72 79 20 61 6c 6c  sys5] memory all
bd90: 6f 63 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ocator..**.** {H
bda0: 31 34 31 36 38 7d 20 41 20 73 75 63 63 65 73 73  14168} A success
bdb0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
bdc0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
bdd0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
bde0: 41 53 49 44 45 5d 2c 5a 2c 4e 29 0a 2a 2a 20 20  ASIDE],Z,N).**  
bdf0: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 63 61          shall ca
be00: 75 73 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  use the default 
be10: 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
be20: 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
be30: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 20 20  figuration.**   
be40: 20 20 20 20 20 20 20 66 6f 72 20 6e 65 77 20 5b         for new [
be50: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
be60: 69 6f 6e 73 5d 20 74 6f 20 62 65 20 4e 20 73 6c  ions] to be N sl
be70: 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73 20 65  ots of Z bytes e
be80: 61 63 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ach..*/.SQLITE_E
be90: 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
bea0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
beb0: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
bec0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
bed0: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
bee0: 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 32  nnections  {H142
bef0: 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20  00} <S20000>.** 
bf00: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
bf10: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
bf20: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
bf30: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
bf40: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
bf50: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
bf60: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
bf70: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
bf80: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
bf90: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
bfa0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
bfb0: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
bfc0: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
bfd0: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
bfe0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
bff0: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
c000: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
c010: 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  ).  The.** sqlit
c020: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
c030: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c  nterface can onl
c040: 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69  y be used immedi
c050: 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74  ately after.** t
c060: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
c070: 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  ection is create
c080: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c090: 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _open()],.** [sq
c0a0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
c0b0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
c0c0: 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a  n_v2()].  .**.**
c0d0: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
c0e0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c0f0: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
c100: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  .)  is the.** co
c110: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
c120: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
c130: 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  de that indicate
c140: 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74  s what.** aspect
c150: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
c160: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
c170: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
c180: 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63  d..** The only c
c190: 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76  hoice for this v
c1a0: 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  alue is [SQLITE_
c1b0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
c1c0: 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62  DE]..** New verb
c1d0: 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
c1e0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
c1f0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
c200: 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69  QLite..** Additi
c210: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64  onal arguments d
c220: 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72  epend on the ver
c230: 62 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  b..**.** INVARIA
c240: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32  NTS:.**.** {H142
c250: 30 33 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  03} A call to [s
c260: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c270: 28 44 2c 56 2c 2e 2e 2e 29 5d 20 73 68 61 6c 6c  (D,V,...)] shall
c280: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
c290: 4f 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  OK].**          
c2a0: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
c2b0: 68 65 20 63 61 6c 6c 20 69 73 20 73 75 63 63 65  he call is succe
c2c0: 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ssful..**.** {H1
c2d0: 34 32 30 36 7d 20 49 66 20 6f 6e 65 20 6f 72 20  4206} If one or 
c2e0: 6d 6f 72 65 20 73 6c 6f 74 73 20 6f 66 20 74 68  more slots of th
c2f0: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  e [lookaside mem
c300: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66  ory allocator] f
c310: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
c320: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c330: 69 6f 6e 5d 20 44 20 61 72 65 20 69 6e 20 75 73  ion] D are in us
c340: 65 2c 20 74 68 65 6e 20 61 20 63 61 6c 6c 20 74  e, then a call t
c350: 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
c360: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c370: 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ](D,[SQLITE_DBCO
c380: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
c390: 2e 2e 2e 29 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  ...) shall.**   
c3a0: 20 20 20 20 20 20 20 66 61 69 6c 20 77 69 74 68         fail with
c3b0: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59   an [SQLITE_BUSY
c3c0: 5d 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0a 2a  ] return code..*
c3d0: 2a 0a 2a 2a 20 7b 48 31 34 32 30 39 7d 20 41 20  *.** {H14209} A 
c3e0: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
c3f0: 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  to .**          
c400: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
c410: 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42  ig](D,[SQLITE_DB
c420: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
c430: 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a  ],B,Z,N) where.*
c440: 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73 20  *          D is 
c450: 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  an open [databas
c460: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
c470: 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 70 6f  d Z and N are po
c480: 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  sitive.**       
c490: 20 20 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20     integers and 
c4a0: 42 20 69 73 20 61 6e 20 61 6c 69 67 6e 65 64 20  B is an aligned 
c4b0: 62 75 66 66 65 72 20 61 74 20 6c 65 61 73 74 20  buffer at least 
c4c0: 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  Z*N bytes in siz
c4d0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  e.**          sh
c4e0: 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 5b 6c  all cause the [l
c4f0: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
c500: 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44  allocator] for D
c510: 20 74 6f 20 75 73 65 20 62 75 66 66 65 72 20 42   to use buffer B
c520: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69   .**          wi
c530: 74 68 20 4e 20 73 6c 6f 74 73 20 6f 66 20 5a 20  th N slots of Z 
c540: 62 79 74 65 73 20 65 61 63 68 2e 0a 2a 2a 0a 2a  bytes each..**.*
c550: 2a 20 7b 48 31 34 32 31 32 7d 20 41 20 73 75 63  * {H14212} A suc
c560: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
c570: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
c580: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 5d  lite3_db_config]
c590: 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  (D,[SQLITE_DBCON
c5a0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42  FIG_LOOKASIDE],B
c5b0: 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a 2a 20 20  ,Z,N) where.**  
c5c0: 20 20 20 20 20 20 20 20 44 20 69 73 20 61 6e 20          D is an 
c5d0: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
c5e0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5a  onnection] and Z
c5f0: 20 61 6e 64 20 4e 20 61 72 65 20 70 6f 73 69 74   and N are posit
c600: 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
c610: 69 6e 74 65 67 65 72 73 20 61 6e 64 20 42 20 69  integers and B i
c620: 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  s NULL pointer s
c630: 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 0a 2a  hall cause the.*
c640: 2a 20 20 20 20 20 20 20 20 20 20 5b 6c 6f 6f 6b  *          [look
c650: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
c660: 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44 20 74 6f  ocator] for D to
c670: 20 61 20 6f 62 74 61 69 6e 20 5a 2a 4e 20 62 79   a obtain Z*N by
c680: 74 65 20 62 75 66 66 65 72 0a 2a 2a 20 20 20 20  te buffer.**    
c690: 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 70        from the p
c6a0: 72 69 6d 61 72 79 20 6d 65 6d 6f 72 79 20 61 6c  rimary memory al
c6b0: 6c 6f 63 61 74 6f 72 20 61 6e 64 20 75 73 65 20  locator and use 
c6c0: 74 68 61 74 20 62 75 66 66 65 72 0a 2a 2a 20 20  that buffer.**  
c6d0: 20 20 20 20 20 20 20 20 77 69 74 68 20 4e 20 6c          with N l
c6e0: 6f 6f 6b 61 73 69 64 65 20 73 6c 6f 74 73 20 6f  ookaside slots o
c6f0: 66 20 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a  f Z bytes each..
c700: 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31 35 7d 20 41  **.** {H14215} A
c710: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
c720: 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   to .**         
c730: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
c740: 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44  fig](D,[SQLITE_D
c750: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
c760: 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a  E],B,Z,N) where.
c770: 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73  **          D is
c780: 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61   an open [databa
c790: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
c7a0: 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 7a  nd Z and N are z
c7b0: 65 72 6f 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20  ero shall.**    
c7c0: 20 20 20 20 20 20 64 69 73 61 62 6c 65 20 74 68        disable th
c7d0: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  e [lookaside mem
c7e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66  ory allocator] f
c7f0: 6f 72 20 44 2e 0a 2a 2a 0a 2a 2a 0a 2a 2f 0a 53  or D..**.**.*/.S
c800: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
c810: 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  AL int sqlite3_d
c820: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
c830: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
c840: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c850: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
c860: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31  ion Routines {H1
c870: 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a  0155} <S20120>.*
c880: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
c890: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
c8a0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
c8b0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
c8c0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
c8d0: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
c8e0: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
c8f0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
c900: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
c910: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
c920: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
c930: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
c940: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
c950: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
c960: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
c970: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
c980: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
c990: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
c9a0: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
c9b0: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
c9c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
c9d0: 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74  LLOC].  By creat
c9e0: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
c9f0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
ca00: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
ca10: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
ca20: 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f  fig()] during co
ca30: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a  nfiguration, an.
ca40: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  ** application c
ca50: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
ca60: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
ca70: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
ca80: 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c  ystem.** for SQL
ca90: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
caa0: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
cab0: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
cac0: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
cad0: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
cae0: 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  h a built-in mem
caf0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
cb00: 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74  at is.** perfect
cb10: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
cb20: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
cb30: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
cb40: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
cb50: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
cb60: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
cb70: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
cb80: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
cb90: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
cba0: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
cbb0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
cbc0: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
cbd0: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
cbe0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
cbf0: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
cc00: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
cc10: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
cc20: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
cc30: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
cc40: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
cc50: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
cc60: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
cc70: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
cc80: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
cc90: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
cca0: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
ccb0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
ccc0: 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64  lloc, xFree, and
ccd0: 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64   xRealloc method
cce0: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
ccf0: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
cd00: 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65  , free(), and re
cd10: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e  alloc() function
cd20: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
cd30: 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ard library..**.
cd40: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
cd50: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
cd60: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
cd70: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
cd80: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
cd90: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
cda0: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
cdb0: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
cdc0: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
cdd0: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
cde0: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
cdf0: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
ce00: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
ce10: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
ce20: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
ce30: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
ce40: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
ce50: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
ce60: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
ce70: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
ce80: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
ce90: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
cea0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
ceb0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
cec0: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
ced0: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
cee0: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
cef0: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
cf00: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
cf10: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
cf20: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a   power of 2..**.
cf30: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
cf40: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
cf50: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
cf60: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
cf70: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
cf80: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
cf90: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
cfa0: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
cfb0: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
cfc0: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
cfd0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
cfe0: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
cff0: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
d000: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
d010: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
d020: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
d030: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
d040: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
d050: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
d060: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
d070: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
d080: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
d090: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79  xShutdown..*/.ty
d0a0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
d0b0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d0c0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
d0d0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
d0e0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d0f0: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
d100: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
d110: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
d120: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
d130: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
d140: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
d150: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
d160: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
d170: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
d180: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
d190: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
d1a0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
d1b0: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
d1c0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
d1d0: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
d1e0: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
d1f0: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
d200: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
d210: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
d220: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
d230: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
d240: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
d250: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
d260: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
d270: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
d280: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
d290: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
d2a0: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
d2b0: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
d2c0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
d2d0: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
d2e0: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
d2f0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
d300: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
d310: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
d320: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
d330: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
d340: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31  tion Options {H1
d350: 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0160} <S20000>.*
d360: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
d370: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
d380: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
d390: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
d3a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d3b0: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
d3c0: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
d3d0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
d3e0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
d3f0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
d400: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
d410: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d420: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
d430: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
d440: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
d450: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
d460: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d470: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
d480: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
d490: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
d4a0: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
d4b0: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
d4c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d4d0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
d4e0: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
d4f0: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
d500: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
d510: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
d520: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
d530: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
d540: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
d550: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
d560: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d570: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
d580: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
d590: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d5a0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
d5b0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
d5c0: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
d5d0: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
d5e0: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e  on.  This option
d5f0: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
d600: 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
d610: 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
d620: 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
d630: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
d640: 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
d650: 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  hread.</dd>.**.*
d660: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d670: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
d680: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
d690: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
d6a0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
d6b0: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
d6c0: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
d6d0: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
d6e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
d6f0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
d700: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
d710: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
d720: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
d730: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
d740: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
d750: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d760: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
d770: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
d780: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
d790: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
d7a0: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
d7b0: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
d7c0: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
d7d0: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
d7e0: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
d7f0: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
d800: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
d810: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
d820: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d830: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
d840: 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65 20 5b  time.  See the [
d850: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 0a  threading mode].
d860: 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  ** documentation
d870: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
d880: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64  information.</dd
d890: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d8a0: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
d8b0: 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
d8c0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
d8d0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
d8e0: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
d8f0: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
d900: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
d910: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
d920: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
d930: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
d940: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
d950: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
d960: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
d970: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
d980: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
d990: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
d9a0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d9b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
d9c0: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
d9d0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
d9e0: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
d9f0: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
da00: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
da10: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
da20: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
da30: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
da40: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
da50: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
da60: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
da70: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
da80: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
da90: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
daa0: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
dab0: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
dac0: 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  ..** See the [th
dad0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
dae0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
daf0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
db00: 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  mation.</dd>.**.
db10: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
db20: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
db30: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
db40: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
db50: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
db60: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
db70: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
db80: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
db90: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
dba0: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
dbb0: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
dbc0: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
dbd0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
dbe0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
dbf0: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
dc00: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
dc10: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
dc20: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
dc30: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
dc40: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
dc50: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
dc60: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
dc70: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
dc80: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
dc90: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
dca0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
dcb0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
dcc0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
dcd0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
dce0: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
dcf0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
dd00: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
dd10: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
dd20: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
dd30: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
dd40: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
dd50: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
dd60: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
dd70: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
dd80: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
dd90: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
dda0: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
ddb0: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
ddc0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ddd0: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
dde0: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
ddf0: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
de00: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
de10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
de20: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
de30: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
de40: 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
de50: 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
de60: 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
de70: 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
de80: 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
de90: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
dea0: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
deb0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
dec0: 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 57  ** statistics. W
ded0: 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68  hen disabled, th
dee0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
def0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
df00: 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65  come .** non-ope
df10: 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
df20: 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
df30: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
df40: 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
df50: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
df60: 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
df70: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
df80: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
df90: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
dfa0: 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
dfb0: 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f  **   </ul>.** </
dfc0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
dfd0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
dfe0: 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
dff0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
e000: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
e010: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
e020: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
e030: 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
e040: 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
e050: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
e060: 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74  ts:  A pointer t
e070: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68  o the memory, th
e080: 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
e090: 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  h scratch buffer
e0a0: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
e0b0: 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72 73  umber of buffers
e0c0: 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a   (N).  The sz.**
e0d0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
e0e0: 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  e a multiple of 
e0f0: 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61 6d  16. The sz param
e100: 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61  eter should be a
e110: 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c 61   few bytes.** la
e120: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61 63  rger than the ac
e130: 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70 61  tual scratch spa
e140: 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65 20  ce required due 
e150: 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61  internal overhea
e160: 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 0a  d..** The first.
e170: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
e180: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
e190: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
e1a0: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
e1b0: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   of memory..** S
e1c0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
e1d0: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  o more than one 
e1e0: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 61  scratch buffer a
e1f0: 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61  t once per threa
e200: 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  d, so.** N shoul
e210: 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20  d be set to the 
e220: 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
e230: 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
e240: 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70  ds.  The sz.** p
e250: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
e260: 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20 73  be 6 times the s
e270: 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
e280: 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
e290: 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63   size..** Scratc
e2a0: 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75 73  h buffers are us
e2b0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
e2c0: 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20  e btree balance 
e2d0: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a  operation.  If.*
e2e0: 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c 61  * The btree bala
e2f0: 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69 74  ncer needs addit
e300: 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79  ional memory bey
e310: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
e320: 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74  ided by.** scrat
e330: 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69 66  ch buffers or if
e340: 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66 66   no scratch buff
e350: 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65 63  er space is spec
e360: 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69  ified, then SQLi
e370: 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73  te.** goes to [s
e380: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
e390: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
e3a0: 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c  emory it needs.<
e3b0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e3c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
e3d0: 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
e3e0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
e3f0: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
e400: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
e410: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
e420: 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64  use for.** the d
e430: 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
e440: 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
e450: 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ult page cache i
e460: 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a  mplemenation.  .
e470: 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
e480: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
e490: 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
e4a0: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
e4b0: 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
e4c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
e4d0: 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
e4e0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
e4f0: 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a  _PCACHE option..
e500: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
e510: 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
e520: 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70  this option: A p
e530: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
e540: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
e550: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
e560: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
e570: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
e580: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
e590: 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  sz argument must
e5a0: 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74   be a power of t
e5b0: 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
e5c0: 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 20 66  nd 32768.  The f
e5d0: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
e5e0: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
e5f0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
e600: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
e610: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
e620: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
e630: 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
e640: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
e650: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
e660: 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
e670: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
e680: 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
e690: 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
e6a0: 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 64  to cache.  If ad
e6b0: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
e6c0: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
e6d0: 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
e6e0: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
e6f0: 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
e700: 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
e710: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
e720: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
e730: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
e740: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
e750: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
e760: 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20  n might use one 
e770: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e  or more of the N
e780: 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64   buffers to hold
e790: 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f   .** memory acco
e7a0: 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69  unting informati
e7b0: 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  on. </dd>.**.** 
e7c0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
e7d0: 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
e7e0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
e7f0: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
e800: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
e810: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
e820: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
e830: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
e840: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e850: 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
e860: 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
e870: 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
e880: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
e890: 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
e8a0: 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
e8b0: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
e8c0: 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f   arguments: A po
e8d0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
e8e0: 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ory, the number 
e8f0: 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
e900: 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
e910: 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
e920: 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
e930: 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66 69  e.  If.** the fi
e940: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
e950: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
e960: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
e970: 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
e980: 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
e990: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
e9a0: 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
e9b0: 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
e9c0: 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
e9d0: 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
e9e0: 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
e9f0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
ea00: 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a  ALLOC].  If the.
ea10: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
ea20: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
ea30: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
ea40: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
ea50: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
ea60: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
ea70: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
ea80: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
ea90: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
eaa0: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
eab0: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
eac0: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
ead0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
eae0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
eaf0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
eb00: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
eb10: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
eb20: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
eb30: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
eb40: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
eb50: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
eb60: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
eb70: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
eb80: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
eb90: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
eba0: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
ebb0: 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
ebc0: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
ebd0: 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
ebe0: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
ebf0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
ec00: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
ec10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
ec20: 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
ec30: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
ec40: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
ec50: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
ec60: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
ec70: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
ec80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
ec90: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
eca0: 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
ecb0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
ecc0: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
ecd0: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
ece0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
ecf0: 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
ed00: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20  utines..** This 
ed10: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
ed20: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
ed30: 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
ed40: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
ed50: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
ed60: 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
ed70: 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
ed80: 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
ed90: 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
eda0: 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
edb0: 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ample.</dd>.**.*
edc0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
edd0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
ede0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
edf0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
ee00: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
ee10: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66  etermine the def
ee20: 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  ault.** memory a
ee30: 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69  llcation lookasi
ee40: 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e  de optimization.
ee50: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
ee60: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
ee70: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
ee80: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
ee90: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
eea0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
eeb0: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
eec0: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
eed0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
eee0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
eef0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
ef00: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
ef10: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
ef20: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
ef30: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
ef40: 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61   pointer to.** a
ef50: 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
ef60: 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
ef70: 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
ef80: 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
ef90: 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
efa0: 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
efb0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
efc0: 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  .  SQLite makes 
efd0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
efe0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73   object and uses
eff0: 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63   it for page cac
f000: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
f010: 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  tions.</dd>.**.*
f020: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
f030: 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64  FIG_GETPCACHE</d
f040: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
f050: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
f060: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
f070: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
f080: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
f090: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
f0a0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  s] object.  SQLi
f0b0: 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65  te copies of the
f0c0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65   current.** page
f0d0: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
f0e0: 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
f0f0: 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
f100: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
f110: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
f120: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
f130: 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
f140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
f150: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
f160: 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
f170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f180: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
f190: 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
f1a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f1b0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
f1c0: 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
f1d0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
f1e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f1f0: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
f200: 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
f210: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
f220: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f230: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
f240: 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
f250: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
f260: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
f270: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
f280: 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
f290: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
f2a0: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
f2b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
f2c0: 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
f2d0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
f2e0: 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
f2f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f300: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
f310: 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
f320: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f330: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
f340: 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
f350: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
f360: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
f370: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
f380: 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
f390: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
f3a0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
f3b0: 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
f3c0: 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
f3d0: 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
f3e0: 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
f3f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f400: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
f410: 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
f420: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f430: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
f440: 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c        14  /* sql
f450: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
f460: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
f470: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
f480: 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f  TPCACHE    15  /
f490: 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
f4a0: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a  _methods* */../*
f4b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
f4c0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
f4d0: 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c 53 32  ons {H10170} <S2
f4e0: 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0000>.** EXPERIM
f4f0: 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ENTAL.**.** Thes
f500: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
f510: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
f520: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
f530: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
f540: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
f550: 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
f560: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
f570: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
f580: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
f590: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
f5a0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
f5b0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
f5c0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
f5d0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
f5e0: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
f5f0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
f600: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
f610: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
f620: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
f630: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
f640: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
f650: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
f660: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
f670: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
f680: 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
f690: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
f6a0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
f6b0: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
f6c0: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
f6d0: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
f6e0: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
f6f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f700: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
f710: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
f720: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
f730: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
f740: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
f750: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
f760: 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
f770: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
f780: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
f790: 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
f7a0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
f7b0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
f7c0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
f7d0: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
f7e0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f7f0: 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
f800: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
f810: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
f820: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
f830: 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
f840: 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
f850: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 20  kaside memory.  
f860: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
f870: 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c  ument may be NUL
f880: 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
f890: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
f8a0: 63 61 74 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  cate the lookasi
f8b0: 64 65 0a 2a 2a 20 62 75 66 66 65 72 20 69 74 73  de.** buffer its
f8c0: 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
f8d0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54  e3_malloc()].  T
f8e0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
f8f0: 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
f900: 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
f910: 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
f920: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 61 72  and the third ar
f930: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
f940: 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
f950: 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
f960: 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
f970: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
f980: 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
f990: 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
f9a0: 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
f9b0: 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
f9c0: 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
f9d0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  s.</dd>.**.** </
f9e0: 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
f9f0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
fa00: 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31  OOKASIDE    1001
fa10: 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
fa20: 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt */.../*.** CA
fa30: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
fa40: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
fa50: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
fa60: 7b 48 31 32 32 30 30 7d 20 3c 53 31 30 37 30 30  {H12200} <S10700
fa70: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
fa80: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
fa90: 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
faa0: 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
fab0: 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
fac0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
fad0: 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
fae0: 66 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78  f SQLite. The ex
faf0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
fb00: 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
fb10: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
fb20: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
fb30: 6d 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73  mpatibility cons
fb40: 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  iderations..**.*
fb50: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
fb60: 0a 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45 61 63  .** {H12201} Eac
fb70: 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20  h new [database 
fb80: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c  connection] shal
fb90: 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20 20  l have the.**   
fba0: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
fbb0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
fbc0: 65 61 74 75 72 65 20 64 69 73 61 62 6c 65 64 20  eature disabled 
fbd0: 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
fbe0: 2a 20 7b 48 31 32 32 30 32 7d 20 54 68 65 20 5b  * {H12202} The [
fbf0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
fc00: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c  _result_codes(D,
fc10: 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  F)] interface sh
fc20: 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20  all enable.**   
fc30: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
fc40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
fc50: 6f 72 20 74 68 65 20 20 5b 64 61 74 61 62 61 73  or the  [databas
fc60: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
fc70: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74  **          if t
fc80: 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 20 69  he F parameter i
fc90: 73 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62  s true, or disab
fca0: 6c 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20  le them if F is 
fcb0: 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  false..*/.int sq
fcc0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
fcd0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
fce0: 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
fcf0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fd00: 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
fd10: 6f 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c 53  owid {H12220} <S
fd20: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63  10700>.**.** Eac
fd30: 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
fd40: 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
fd50: 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
fd60: 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
fd70: 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
fd80: 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
fd90: 5d 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20  ]. The rowid is 
fda0: 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
fdb0: 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
fdc0: 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
fdd0: 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
fde0: 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
fdf0: 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
fe00: 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
fe10: 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
fe20: 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
fe30: 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74  mns. If.** the t
fe40: 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
fe50: 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
fe60: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
fe70: 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
fe80: 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
fe90: 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
fea0: 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  id..**.** This r
feb0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
fec0: 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
fed0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
fee0: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
fef0: 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61  ERT] into the da
ff00: 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20  tabase from the 
ff10: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ff20: 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
ff30: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20  first argument. 
ff40: 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75   If no successfu
ff50: 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
ff60: 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
ff70: 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
ff80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
ff90: 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
ffa0: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 5b 49 4e  .**.** If an [IN
ffb0: 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
ffc0: 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74  hin a trigger, t
ffd0: 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  hen the [rowid] 
ffe0: 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
fff0: 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e  ** row is return
10000 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
10010 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ne as long as th
10020 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e  e trigger is run
10030 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
10040 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65  e the trigger te
10050 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61  rminates, the va
10060 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
10070 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
10080 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c  reverts to the l
10090 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74  ast value insert
100a0 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  ed before the tr
100b0 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a  igger fired..**.
100c0 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  ** An [INSERT] t
100d0 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
100e0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
100f0 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
10100 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
10110 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
10120 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
10130 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
10140 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
10150 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20  e.  Thus INSERT 
10160 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
10170 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
10180 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
10190 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
101a0 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
101b0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
101c0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
101d0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
101e0 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
101f0 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49  n fails.  When I
10200 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
10210 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
10220 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
10230 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
10240 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
10250 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
10260 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
10270 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
10280 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
10290 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
102a0 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
102b0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
102c0 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
102d0 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
102e0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
102f0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46  terface..**.** F
10300 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
10310 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
10320 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
10330 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
10340 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
10350 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
10360 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
10370 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   back..**.** INV
10380 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
10390 48 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c  H12221} The [sql
103a0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
103b0 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69  _rowid()] functi
103c0 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a  on shall return.
103d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
103e0 5b 72 6f 77 69 64 5d 0a 2a 2a 20 20 20 20 20 20  [rowid].**      
103f0 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73 74 20      of the most 
10400 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
10410 6c 20 5b 49 4e 53 45 52 54 5d 20 70 65 72 66 6f  l [INSERT] perfo
10420 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61 6d 65  rmed on the same
10430 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
10440 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10450 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68  n] and within th
10460 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72  e same or higher
10470 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20   level.**       
10480 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65     trigger conte
10490 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74  xt, or zero if t
104a0 68 65 72 65 20 68 61 76 65 20 62 65 65 6e 20 6e  here have been n
104b0 6f 20 71 75 61 6c 69 66 79 69 6e 67 0a 2a 2a 20  o qualifying.** 
104c0 20 20 20 20 20 20 20 20 20 5b 49 4e 53 45 52 54           [INSERT
104d0 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
104e0 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20 54 68 65  .** {H12223} The
104f0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
10500 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66  nsert_rowid()] f
10510 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65  unction shall re
10520 74 75 72 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  turn the.**     
10530 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20       same value 
10540 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
10550 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
10560 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20  r context.**    
10570 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c        immediatel
10580 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74  y before and aft
10590 65 72 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  er a [ROLLBACK].
105a0 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
105b0 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 33  NS:.**.** {A1223
105c0 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65  2} If a separate
105d0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
105e0 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
105f0 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  on the same.**  
10600 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
10610 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
10620 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
10630 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
10640 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
10650 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
10660 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
10670 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
10680 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
10690 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
106a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
106b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
106c0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
106d0 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
106e0 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20    unpredictable 
106f0 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
10700 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
10710 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
10720 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20 69            last i
10730 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
10740 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
10750 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
10760 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
10770 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
10780 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
10790 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
107a0 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d  odified {H12240}
107b0 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10600>.**.** 
107c0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
107d0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
107e0 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
107f0 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
10800 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
10810 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
10820 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
10830 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
10840 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
10850 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
10860 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
10870 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
10880 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
10890 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
108a0 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
108b0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
108c0 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
108d0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
108e0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
108f0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
10900 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
10910 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
10920 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  rs are not count
10930 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
10940 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
10950 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  es()] function.*
10960 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  * to find the to
10970 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
10980 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  anges including 
10990 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
109a0 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a  y triggers..**.*
109b0 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  * A "row change"
109c0 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
109d0 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
109e0 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
109f0 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
10a00 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
10a10 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
10a20 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
10a30 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
10a40 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
10a50 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
10a60 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
10a70 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
10a80 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44  RT processing, D
10a90 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79  ROP TABLE, or by
10aa0 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   any other.** me
10ab0 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20  chanisms do not 
10ac0 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20  count as direct 
10ad0 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
10ae0 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f  ** A "trigger co
10af0 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70  ntext" is a scop
10b00 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74  e of execution t
10b10 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a  hat begins and.*
10b20 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20  * ends with the 
10b30 73 63 72 69 70 74 20 6f 66 20 61 20 74 72 69 67  script of a trig
10b40 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73  ger.  Most SQL s
10b50 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
10b60 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
10b70 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
10b80 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
10b90 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
10ba0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
10bb0 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
10bc0 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
10bd0 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
10be0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
10bf0 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
10c00 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
10c10 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
10c20 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
10c30 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
10c40 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
10c50 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43  uration..**.** C
10c60 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
10c70 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
10c80 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
10c90 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
10ca0 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
10cb0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
10cc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
10cd0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
10ce0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
10cf0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
10d00 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
10d10 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
10d20 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
10d30 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
10d40 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
10d50 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
10d60 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61  ** Thus, when ca
10d70 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
10d80 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
10d90 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
10da0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
10db0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
10dc0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
10dd0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
10de0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
10df0 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
10e00 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69  e top level.  Wi
10e10 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
10e20 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
10e30 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
10e40 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
10e50 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
10e60 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
10e70 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
10e80 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
10e90 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
10ea0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
10eb0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
10ec0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
10ed0 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
10ee0 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
10ef0 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
10f00 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
10f10 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
10f20 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
10f30 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
10f40 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
10f50 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a  r own context..*
10f60 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
10f70 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61  ements the comma
10f80 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  nd "DELETE FROM 
10f90 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61  table" without a
10fa0 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a   WHERE clause.**
10fb0 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64   by dropping and
10fc0 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20   recreating the 
10fd0 74 61 62 6c 65 2e 20 20 44 6f 69 6e 67 20 73 6f  table.  Doing so
10fe0 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20   is much faster 
10ff0 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68  than going.** th
11000 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69  rough and deleti
11010 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c  ng individual el
11020 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20  ements from the 
11030 74 61 62 6c 65 2e 20 20 42 65 63 61 75 73 65 20  table.  Because 
11040 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d  of this.** optim
11050 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c  ization, the del
11060 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54  etions in "DELET
11070 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72  E FROM table" ar
11080 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65  e not row change
11090 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f  s and.** will no
110a0 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20  t be counted by 
110b0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
110c0 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65  ges() or [sqlite
110d0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
110e0 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c  )].** functions,
110f0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
11100 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
11110 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
11120 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e  originally.** in
11130 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20   the table.  To 
11140 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
11150 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
11160 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
11170 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
11180 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
11190 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
111a0 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75    Or recompile u
111b0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
111c0 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54  ITE_OMIT_TRUNCAT
111d0 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20  E_OPTIMIZATION] 
111e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
111f0 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ion to disable t
11200 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  he.** optimizati
11210 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65  on on all querie
11220 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
11230 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  NTS:.**.** {H122
11240 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
11250 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
11260 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72  tion shall retur
11270 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  n the number of.
11280 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 20  **          row 
11290 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
112a0 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
112b0 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
112c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
112d0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
112e0 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  t on the same da
112f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11300 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  n and.**        
11310 20 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d    within the sam
11320 65 20 6f 72 20 68 69 67 68 65 72 20 74 72 69 67  e or higher trig
11330 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20  ger context, or 
11340 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61  zero if there ha
11350 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ve.**          n
11360 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c  ot been any qual
11370 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67  ifying row chang
11380 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34  es..**.** {H1224
11390 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66  3} Statements of
113a0 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54   the form "DELET
113b0 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65  E FROM tablename
113c0 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20  " with no.**    
113d0 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 75        WHERE clau
113e0 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73  se shall cause s
113f0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
11400 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
11410 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
11420 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72  )] to return zer
11430 6f 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  o, regardless of
11440 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
11450 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
11460 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68  originally in th
11470 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41  e table..**.** A
11480 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
11490 2a 20 7b 41 31 32 32 35 32 7d 20 49 66 20 61 20  * {A12252} If a 
114a0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
114b0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
114c0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
114d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
114e0 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 20            while 
114f0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
11500 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
11510 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
11520 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  turned.**       
11530 20 20 20 69 73 20 75 6e 70 72 65 64 69 63 74 61     is unpredicta
11540 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
11550 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
11560 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
11570 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
11580 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
11590 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
115a0 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 36 30  Modified {H12260
115b0 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10600>.**.**
115c0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
115d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
115e0 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
115f0 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52   caused by INSER
11600 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20  T,.** UPDATE or 
11610 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
11620 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
11630 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11640 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
11650 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75   The count inclu
11660 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20  des all changes 
11670 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72  from all trigger
11680 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65   contexts.  Howe
11690 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
116a0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
116b0 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
116c0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50  to implement REP
116d0 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73  LACE constraints
116e0 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
116f0 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
11700 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74  ssing, or DROP t
11710 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e  able processing.
11720 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20  .** The changes 
11730 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73  are counted as s
11740 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65  oon as the state
11750 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
11760 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c  them is.** compl
11770 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
11780 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
11790 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
117a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
117b0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
117c0 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
117d0 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
117e0 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
117f0 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
11800 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48  le" without a WH
11810 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79  ERE clause.** by
11820 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
11830 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
11840 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75  le.  (This is mu
11850 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67  ch faster than g
11860 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20  oing.** through 
11870 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64  and deleting ind
11880 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73  ividual elements
11890 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e   from the table.
118a0 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  )  Because of th
118b0 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  is.** optimizati
118c0 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e  on, the deletion
118d0 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f  s in "DELETE FRO
118e0 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74  M table" are not
118f0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64   row changes and
11900 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  .** will not be 
11910 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73  counted by the s
11920 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
11930 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   or [sqlite3_tot
11940 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a  al_changes()].**
11950 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61   functions, rega
11960 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
11970 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
11980 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
11990 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20  nally.** in the 
119a0 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61  table.  To get a
119b0 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
119c0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
119d0 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20  f rows deleted, 
119e0 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46  use.** "DELETE F
119f0 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
11a00 31 22 20 69 6e 73 74 65 61 64 2e 20 20 20 4f 72  1" instead.   Or
11a10 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67   recompile using
11a20 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
11a30 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50  OMIT_TRUNCATE_OP
11a40 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70  TIMIZATION] comp
11a50 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11a60 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a  to disable the.*
11a70 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f  * optimization o
11a80 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a  n all queries..*
11a90 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
11aa0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
11ab0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
11ac0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
11ad0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 31  S:.**.** {H12261
11ae0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  } The [sqlite3_t
11af0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
11b00 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61  returns the tota
11b10 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20  l number.**     
11b20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68 61 6e       of row chan
11b30 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e  ges caused by IN
11b40 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e  SERT, UPDATE, an
11b50 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20  d/or DELETE.**  
11b60 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
11b70 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ts on the same [
11b80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11b90 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20  ion], in any.** 
11ba0 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72           trigger
11bb0 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20   context, since 
11bc0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
11bd0 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72 65 61  nection was crea
11be0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ted..**.** {H122
11bf0 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f  63} Statements o
11c00 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45  f the form "DELE
11c10 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d  TE FROM tablenam
11c20 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20  e" with no.**   
11c30 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61         WHERE cla
11c40 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68  use shall not ch
11c50 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
11c60 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20  eturned.**      
11c70 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
11c80 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
11c90 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
11ca0 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32  ONS:.**.** {A122
11cb0 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  64} If a separat
11cc0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
11cd0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
11ce0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
11cf0 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
11d00 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
11d10 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
11d20 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
11d30 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
11d40 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65           returne
11d50 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
11d60 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
11d70 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
11d80 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
11d90 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
11da0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11db0 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
11dc0 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b  -Running Query {
11dd0 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e  H12270} <S30500>
11de0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
11df0 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
11e00 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
11e10 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
11e20 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
11e30 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
11e40 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
11e50 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
11e60 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
11e70 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
11e80 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
11e90 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
11ea0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
11eb0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
11ec0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
11ed0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
11ee0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
11ef0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
11f00 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63   It is safe to c
11f10 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
11f20 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
11f30 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
11f40 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
11f50 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
11f60 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
11f70 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
11f80 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
11f90 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
11fa0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
11fb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11fc0 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
11fd0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
11fe0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
11ff0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12000 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
12010 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72  * If an SQL oper
12020 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
12030 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
12040 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
12050 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
12060 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
12070 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
12080 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
12090 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
120a0 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
120b0 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
120c0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
120d0 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61  .** An SQL opera
120e0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
120f0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
12100 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
12110 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74  ERRUPT]..** If t
12120 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
12130 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
12140 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
12150 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
12160 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
12170 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
12180 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
12190 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
121a0 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
121b0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
121c0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
121d0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
121e0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68 61  3_interrupt() ha
121f0 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
12200 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
12210 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
12220 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
12230 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
12240 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  rns..**.** INVAR
12250 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
12260 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2271} The [sqlit
12270 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20  e3_interrupt()] 
12280 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66  interface will f
12290 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67  orce all running
122a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
122b0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
122c0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
122d0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
122e0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
122f0 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74       to halt aft
12300 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74  er processing at
12310 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69   most one additi
12320 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61 74 61  onal row of data
12330 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 32 7d  ..**.** {H12272}
12340 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
12350 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  nt that is inter
12360 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74  rupted by [sqlit
12370 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
12380 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
12390 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
123a0 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a  INTERRUPT]..**.*
123b0 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
123c0 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20 49 66  *.** {A12279} If
123d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
123e0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
123f0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
12400 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20  nterrupt()].**  
12410 20 20 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69          is runni
12420 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
12430 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
12440 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
12450 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12460 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
12470 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
12480 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
12490 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
124a0 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20  mplete {H10510} 
124b0 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70200>.**.** T
124c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
124d0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d  e useful for com
124e0 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
124f0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
12500 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
12510 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
12520 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70  ems to form comp
12530 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74 65  lete a SQL state
12540 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
12550 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
12560 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
12570 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
12580 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
12590 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68  for parsing.  Th
125a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
125b0 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
125c0 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
125d0 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
125e0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
125f0 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65  tement.  A state
12600 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
12610 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
12620 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
12630 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
12640 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
12650 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a  fragment of a.**
12660 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
12670 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69  statement.  Semi
12680 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
12690 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
126a0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
126b0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
126c0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
126d0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
126e0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
126f0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
12700 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
12710 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
12720 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
12730 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
12740 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
12750 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
12760 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
12770 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
12780 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
12790 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
127a0 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
127b0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
127c0 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
127d0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
127e0 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d 20 41  **.** {H10511} A
127f0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 61 6c   successful eval
12800 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  uation of [sqlit
12810 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f  e3_complete()] o
12820 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
12830 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
12840 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20 73  6()] functions s
12850 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
12860 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65 72 69   return a numeri
12870 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  c 1 if and only 
12880 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f 6e 2d  if the last non-
12890 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 20 20  whitespace.**   
128a0 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69 6e 20         token in 
128b0 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 20 61  their input is a
128c0 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 20   semicolon that 
128d0 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65  is not in betwee
128e0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
128f0 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20  e BEGIN and END 
12900 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 49 47  of a CREATE TRIG
12910 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  GER statement..*
12920 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20 49 66  *.** {H10512} If
12930 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
12940 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
12950 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e 76 6f  s during an invo
12960 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  cation.**       
12970 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63     of [sqlite3_c
12980 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20 5b 73  omplete()] or [s
12990 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
129a0 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  6()] then the.**
129b0 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e            routin
129c0 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b  e shall return [
129d0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
129e0 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
129f0 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 32 7d  :.**.** {A10512}
12a00 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
12a10 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
12a20 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
12a30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
12a40 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73           UTF-8 s
12a50 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  tring..**.** {A1
12a60 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20  0513} The input 
12a70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
12a80 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
12a90 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
12aa0 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
12ab0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
12ac0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
12ad0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
12ae0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
12af0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
12b00 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
12b10 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
12b20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
12b30 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
12b40 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
12b50 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
12b60 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30  Y Errors {H12310
12b70 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S40400>.**.**
12b80 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65   This routine se
12b90 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
12ba0 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
12bb0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  t be invoked whe
12bc0 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
12bd0 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
12be0 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
12bf0 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  able that anothe
12c00 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
12c10 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
12c20 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
12c30 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
12c40 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
12c50 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
12c60 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
12c70 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
12c80 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
12c90 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
12ca0 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68   the lock. If th
12cb0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
12cc0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
12cd0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
12ce0 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  k will be invoke
12cf0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
12d00 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
12d10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
12d20 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73  o the handler is
12d30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
12d40 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
12d50 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
12d60 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
12d70 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
12d80 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f  ler().  The seco
12d90 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
12da0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61  * the handler ca
12db0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
12dc0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
12dd0 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
12de0 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
12df0 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
12e00 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
12e10 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20   If the.** busy 
12e20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
12e30 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
12e40 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
12e50 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
12e60 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
12e70 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
12e80 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
12e90 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
12ea0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
12eb0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
12ec0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
12ed0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
12ee0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
12ef0 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
12f00 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
12f10 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
12f20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
12f30 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
12f40 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
12f50 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
12f60 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
12f70 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
12f80 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
12f90 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51  ontention. If SQ
12fa0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
12fb0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
12fc0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
12fd0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
12fe0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
12ff0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
13000 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
13010 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
13020 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13030 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
13040 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
13050 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
13060 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
13070 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
13080 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
13090 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
130a0 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
130b0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
130c0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
130d0 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
130e0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
130f0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
13100 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
13110 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
13120 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
13130 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
13140 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
13150 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
13160 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
13170 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
13180 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
13190 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
131a0 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
131b0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
131c0 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
131d0 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
131e0 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
131f0 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
13200 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
13210 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
13220 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
13230 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
13240 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
13250 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
13260 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
13270 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
13280 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
13290 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
132a0 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
132b0 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
132c0 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
132d0 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  oceed..**.** The
132e0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
132f0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
13300 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
13310 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
13320 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
13330 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13340 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
13350 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
13360 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
13370 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
13380 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
13390 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
133a0 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
133b0 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
133c0 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
133d0 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
133e0 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
133f0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
13400 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
13410 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
13420 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
13430 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
13440 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
13450 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
13460 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
13470 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
13480 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
13490 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61  s.  If it is una
134a0 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
134b0 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
134c0 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
134d0 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
134e0 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
134f0 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
13500 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
13510 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
13520 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
13530 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
13540 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
13550 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
13560 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
13570 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72  CKED].  This err
13580 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
13590 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
135a0 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
135b0 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
135c0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
135d0 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
135e0 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
135f0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
13600 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
13610 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
13620 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
13630 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
13640 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
13650 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
13660 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
13670 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
13680 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
13690 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
136a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
136b0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
136c0 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
136d0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
136e0 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
136f0 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f  set handler.  No
13700 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
13710 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
13720 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
13730 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
13740 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
13750 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
13760 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
13770 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
13780 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
13790 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
137a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
137b0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
137c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
137d0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
137e0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
137f0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
13800 72 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49  r..** .** INVARI
13810 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
13820 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  311} The [sqlite
13830 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
13840 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ,C,A)] function 
13850 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a 2a 2a  shall replace.**
13860 20 20 20 20 20 20 20 20 20 20 62 75 73 79 20 63            busy c
13870 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 20 5b  allback in the [
13880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13890 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 20 6e 65  ion] D with a ne
138a0 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  w.**          a 
138b0 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
138c0 20 43 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69   C and applicati
138d0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
138e0 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 32  A..**.** {H12312
138f0 7d 20 4e 65 77 6c 79 20 63 72 65 61 74 65 64 20  } Newly created 
13900 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13910 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68 61 76  tions] shall hav
13920 65 20 61 20 62 75 73 79 0a 2a 2a 20 20 20 20 20  e a busy.**     
13930 20 20 20 20 20 68 61 6e 64 6c 65 72 20 6f 66 20       handler of 
13940 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  NULL..**.** {H12
13950 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72  314} When two or
13960 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 73 65 20   more [database 
13970 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61  connections] sha
13980 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  re a.**         
13990 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
139a0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20  _shared_cache | 
139b0 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a  common cache],.*
139c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
139d0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
139e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
139f0 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c  nection currentl
13a00 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  y using.**      
13a10 20 20 20 20 74 68 65 20 63 61 63 68 65 20 73 68      the cache sh
13a20 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  all be invoked w
13a30 68 65 6e 20 74 68 65 20 63 61 63 68 65 20 65 6e  hen the cache en
13a40 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e  counters a lock.
13a50 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36 7d 20  .**.** {H12316} 
13a60 49 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  If a busy handle
13a70 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
13a80 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  ns zero, then th
13a90 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
13aa0 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ce.**          t
13ab0 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65  hat provoked the
13ac0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20 73   locking event s
13ad0 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  hall return [SQL
13ae0 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
13af0 20 7b 48 31 32 33 31 38 7d 20 53 51 4c 69 74 65   {H12318} SQLite
13b00 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73 20 74   shall invokes t
13b10 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
13b20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
13b30 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20  ts which.**     
13b40 20 20 20 20 20 61 72 65 20 61 20 63 6f 70 79 20       are a copy 
13b50 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20 73  of the pointer s
13b60 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 33  upplied by the 3
13b70 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
13b80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
13b90 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
13ba0 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74  r()] and a count
13bb0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
13bc0 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20  f prior.**      
13bd0 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20      invocations 
13be0 6f 66 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  of the busy hand
13bf0 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d 65  ler for the same
13c00 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a   locking event..
13c10 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
13c20 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33 31 39  S:.**.** {A12319
13c30 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  } A busy handler
13c40 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
13c50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
13c60 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
13c70 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72 65 64      or [prepared
13c80 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
13c90 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
13ca0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
13cb0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
13cc0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
13cd0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
13ce0 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
13cf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
13d00 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20   A Busy Timeout 
13d10 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34 31 30  {H12340} <S40410
13d20 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
13d30 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
13d40 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
13d50 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
13d60 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
13d70 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
13d80 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
13d90 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
13da0 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e  locked.  The han
13db0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
13dc0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
13dd0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
13de0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
13df0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
13e00 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
13e10 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 74  ed. {H12343} Aft
13e20 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  er "ms" millisec
13e30 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
13e40 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
13e50 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
13e60 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
13e70 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
13e80 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
13e90 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
13ea0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a  OERR_BLOCKED]..*
13eb0 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69  *.** Calling thi
13ec0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
13ed0 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
13ee0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
13ef0 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
13f00 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
13f10 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  lers..**.** Ther
13f20 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
13f30 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
13f40 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
13f50 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
13f60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
13f70 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  y any given mome
13f80 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
13f90 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
13fa0 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
13fb0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
13fc0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
13fd0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
13fe0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
13ff0 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
14000 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
14010 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
14020 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
14030 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  341} The [sqlite
14040 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
14050 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
14060 20 6f 76 65 72 72 69 64 65 20 61 6e 79 20 70 72   override any pr
14070 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ior.**          
14080 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
14090 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c  meout()] or [sql
140a0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
140b0 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20  r()] setting.** 
140c0 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20           on the 
140d0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
140e0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
140f0 2a 20 7b 48 31 32 33 34 33 7d 20 49 66 20 74 68  * {H12343} If th
14100 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
14110 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  to [sqlite3_busy
14120 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c  _timeout()] is l
14130 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  ess than.**     
14140 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f       or equal to
14150 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20   zero, then the 
14160 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61  busy handler sha
14170 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 20 73 6f  ll be cleared so
14180 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
14190 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74    all subsequent
141a0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20   locking events 
141b0 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75  immediately retu
141c0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
141d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 34 7d  ..**.** {H12344}
141e0 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   If the 2nd para
141f0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
14200 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
14210 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a  ] is a positive.
14220 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
14230 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73  er N, then a bus
14240 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20  y handler shall 
14250 62 65 20 73 65 74 20 74 68 61 74 20 72 65 70 65  be set that repe
14260 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20  atedly calls.** 
14270 20 20 20 20 20 20 20 20 20 74 68 65 20 78 53 6c           the xSl
14280 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20  eep() method in 
14290 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
142a0 20 7c 20 56 46 53 20 69 6e 74 65 72 66 61 63 65   | VFS interface
142b0 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20  ] until.**      
142c0 20 20 20 20 65 69 74 68 65 72 20 74 68 65 20 6c      either the l
142d0 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e  ock clears or un
142e0 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69  til the cumulati
142f0 76 65 20 73 6c 65 65 70 20 74 69 6d 65 0a 2a 2a  ve sleep time.**
14300 20 20 20 20 20 20 20 20 20 20 72 65 70 6f 72 74            report
14310 65 64 20 62 61 63 6b 20 62 79 20 78 53 6c 65 65  ed back by xSlee
14320 70 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69  p() exceeds N mi
14330 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69  lliseconds..*/.i
14340 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
14350 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
14360 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
14370 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
14380 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
14390 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
143a0 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20 3c 53  ries {H12370} <S
143b0 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66  10000>.**.** Def
143c0 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
143d0 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
143e0 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
143f0 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
14400 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
14410 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
14420 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
14430 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
14440 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
14450 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
14460 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
14470 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
14480 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
14490 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
144a0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
144b0 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
144c0 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
144d0 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
144e0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
144f0 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
14500 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
14510 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
14520 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
14530 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
14540 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
14550 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
14560 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
14570 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
14580 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
14590 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
145a0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
145b0 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
145c0 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
145d0 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
145e0 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
145f0 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
14600 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
14610 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
14620 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
14630 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
14640 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
14650 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
14660 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
14670 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
14680 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
14690 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
146a0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
146b0 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
146c0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
146d0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
146e0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
146f0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
14700 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
14710 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
14720 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
14730 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
14740 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
14750 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
14760 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
14770 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
14780 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
14790 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
147a0 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
147b0 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
147c0 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
147d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
147e0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73  ble()]..**.** As
147f0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
14800 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
14810 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
14820 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
14830 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
14840 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
14850 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
14860 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
14870 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
14880 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14890 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
148a0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
148b0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
148c0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
148d0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
148e0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
148f0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
14900 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
14910 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
14920 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
14930 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
14940 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
14950 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
14960 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
14970 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
14980 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
14990 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
149a0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
149b0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
149c0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
149d0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
149e0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
149f0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
14a00 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
14a10 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
14a20 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
14a30 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
14a40 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
14a50 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14a60 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
14a70 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
14a80 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
14a90 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14aa0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
14ab0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
14ac0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
14ad0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
14ae0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
14af0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
14b00 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
14b10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
14b20 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
14b30 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
14b40 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
14b50 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
14b60 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
14b70 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
14b80 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
14b90 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
14ba0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
14bb0 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65   It returns a re
14bc0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
14bd0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
14be0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
14bf0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
14c00 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67  fter the calling
14c10 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69   function has fi
14c20 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
14c30 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75   result, it shou
14c40 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70  ld.** pass the p
14c50 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65  ointer to the re
14c60 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71  sult table to sq
14c70 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
14c80 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
14c90 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
14ca0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
14cb0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
14cc0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
14cd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
14ce0 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
14cf0 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
14d00 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
14d10 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
14d20 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
14d30 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
14d40 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
14d50 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
14d60 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14d70 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
14d80 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
14d90 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
14da0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
14db0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14dc0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
14dd0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
14de0 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
14df0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
14e00 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
14e10 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
14e20 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
14e30 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
14e40 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
14e50 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
14e60 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
14e70 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
14e80 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
14e90 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
14ea0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
14eb0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
14ec0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
14ed0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
14ee0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
14ef0 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
14f00 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
14f10 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
14f20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
14f30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
14f40 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  code()] or [sqli
14f50 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
14f60 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
14f70 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31 7d 20  .**.** {H12371} 
14f80 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 67 65  If a [sqlite3_ge
14f90 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 6c 73  t_table()] fails
14fa0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
14fb0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  tion, then.**   
14fc0 20 20 20 20 20 20 20 69 74 20 73 68 61 6c 6c 20         it shall 
14fd0 66 72 65 65 20 74 68 65 20 72 65 73 75 6c 74 20  free the result 
14fe0 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73  table under cons
14ff0 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 20  truction, abort 
15000 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
15010 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73  query in process
15020 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 62 73 65  , skip any subse
15030 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73  quent queries, s
15040 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
15050 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 20 6f 75     *pazResult ou
15060 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20  tput pointer to 
15070 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 20  NULL and return 
15080 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
15090 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d 20 49  **.** {H12373} I
150a0 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e 20 70  f the pnColumn p
150b0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
150c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
150d0 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a  ] is not NULL.**
150e0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 61            then a
150f0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
15100 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
15110 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
15120 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  shall.**        
15130 20 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d 62    write the numb
15140 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
15150 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
15160 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
15170 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70  he query into *p
15180 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  nColumn..**.** {
15190 48 31 32 33 37 34 7d 20 49 66 20 74 68 65 20 70  H12374} If the p
151a0 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74  nRow parameter t
151b0 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  o [sqlite3_get_t
151c0 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e  able()] is not N
151d0 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
151e0 74 68 65 6e 20 61 20 73 75 63 63 65 73 73 66 75  then a successfu
151f0 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
15200 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
15210 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20  le()] shall.**  
15220 20 20 20 20 20 20 20 20 77 72 69 74 65 73 20 74          writes t
15230 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
15240 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  s in the.**     
15250 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20       result set 
15260 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 74  of the query int
15270 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20  o *pnRow..**.** 
15280 7b 48 31 32 33 37 36 7d 20 41 20 73 75 63 63 65  {H12376} A succe
15290 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
152a0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   of [sqlite3_get
152b0 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 74 20 63  _table()] that c
152c0 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20 20 20  omputes.**      
152d0 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 20 72 65      N rows of re
152e0 73 75 6c 74 20 77 69 74 68 20 43 20 63 6f 6c 75  sult with C colu
152f0 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 68 61 6c  mns per row shal
15300 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73 75 6c  l make *pazResul
15310 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  t.**          po
15320 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 61 79 20  int to an array 
15330 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 28  of pointers to (
15340 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 73 20 77  N+1)*C strings w
15350 68 65 72 65 20 74 68 65 20 66 69 72 73 74 0a 2a  here the first.*
15360 2a 20 20 20 20 20 20 20 20 20 20 43 20 73 74 72  *          C str
15370 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d 6e 20  ings are column 
15380 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 69 6e 65  names as obtaine
15390 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  d from.**       
153a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
153b0 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 74  mn_name()] and t
153c0 68 65 20 72 65 73 74 20 61 72 65 20 63 6f 6c 75  he rest are colu
153d0 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c 75 65 73  mn result values
153e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74  .**          obt
153f0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
15400 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
15410 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37  )]..**.** {H1237
15420 39 7d 20 54 68 65 20 76 61 6c 75 65 73 20 69 6e  9} The values in
15430 20 74 68 65 20 70 61 7a 52 65 73 75 6c 74 20 61   the pazResult a
15440 72 72 61 79 20 72 65 74 75 72 6e 65 64 20 62 79  rray returned by
15450 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
15460 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ble()].**       
15470 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69 6e 20     shall remain 
15480 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c 65 61  valid until clea
15490 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  red by [sqlite3_
154a0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
154b0 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20 57 68  *.** {H12382} Wh
154c0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
154d0 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61  rs during evalua
154e0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
154f0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a  _get_table()].**
15500 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66 75            the fu
15510 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74  nction shall set
15520 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f 20 4e   *pazResult to N
15530 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20 65 72  ULL, write an er
15540 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
15550 20 20 20 20 20 20 20 20 69 6e 74 6f 20 6d 65 6d          into mem
15560 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
15570 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
15580 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 20 20  c()], make.**   
15590 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 72 6d 73         **pzErrms
155a0 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20  g point to that 
155b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c 20 61  error message, a
155c0 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 20  nd return a.**  
155d0 20 20 20 20 20 20 20 20 61 70 70 72 6f 70 72 69          appropri
155e0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
155f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
15600 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
15610 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
15620 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
15630 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
15640 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
15650 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
15660 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
15670 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
15680 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
15690 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
156a0 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
156b0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
156c0 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
156d0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
156e0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
156f0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
15700 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
15710 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
15720 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
15730 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
15740 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
15750 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
15760 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
15770 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
15780 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
15790 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
157a0 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
157b0 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30  Functions {H1740
157c0 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30  0} <S70000><S200
157d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
157e0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
157f0 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  kalikes of the "
15800 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
15810 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
15820 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
15830 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
15840 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
15850 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
15860 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
15870 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
15880 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
15890 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
158a0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
158b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
158c0 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
158d0 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
158e0 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
158f0 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
15900 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
15910 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f  ree()].  Both ro
15920 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
15930 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
15940 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
15950 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
15960 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
15970 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
15980 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
15990 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
159a0 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   In sqlite3_snpr
159b0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
159c0 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
159d0 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
159e0 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
159f0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
15a00 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
15a10 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
15a20 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
15a30 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
15a40 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
15a50 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
15a60 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
15a70 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
15a80 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
15a90 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
15aa0 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
15ab0 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
15ac0 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  ().  This is an.
15ad0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
15ae0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
15af0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
15b00 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
15b10 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
15b20 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61  ibility.  Note a
15b30 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
15b40 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
15b50 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
15b60 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
15b70 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
15b80 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
15b90 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
15ba0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
15bb0 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69  buffer.  We admi
15bc0 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
15bd0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
15be0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
15bf0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
15c00 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
15c10 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
15c20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
15c30 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
15c40 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
15c50 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
15c60 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
15c70 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  ility..**.** As 
15c80 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
15c90 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
15ca0 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
15cb0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
15cc0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
15cd0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
15ce0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
15cf0 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66  rminated.  The f
15d00 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
15d10 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
15d20 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
15d30 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
15d40 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
15d50 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
15d60 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
15d70 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
15d80 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
15d90 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
15da0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
15db0 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  rs..**.** These 
15dc0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
15dd0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
15de0 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
15df0 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
15e00 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
15e10 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
15e20 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
15e30 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
15e40 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
15e50 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
15e60 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
15e70 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
15e80 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
15e90 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
15ea0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70  .**.** The %q op
15eb0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
15ec0 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
15ed0 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
15ee0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
15ef0 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
15f00 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
15f10 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
15f20 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
15f30 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
15f40 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
15f50 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
15f60 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20  ng literal.  By 
15f70 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
15f80 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
15f90 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
15fa0 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
15fb0 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
15fc0 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
15fd0 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
15fe0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
15ff0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
16000 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
16010 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
16020 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
16030 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
16040 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
16050 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
16060 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
16070 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
16080 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
16090 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
160a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
160b0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
160c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
160d0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
160e0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
160f0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
16100 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
16110 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
16120 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
16130 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
16140 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
16150 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
16160 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
16170 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
16180 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
16190 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
161a0 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
161b0 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
161c0 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
161d0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
161e0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
161f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
16200 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
16210 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
16220 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
16230 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
16240 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
16250 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
16260 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
16270 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
16280 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
16290 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
162a0 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
162b0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
162c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
162d0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
162e0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
162f0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
16300 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
16310 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
16320 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
16330 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
16340 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
16350 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
16360 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
16370 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
16380 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
16390 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
163a0 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
163b0 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25  ral..**.** The %
163c0 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
163d0 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
163e0 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
163f0 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
16400 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
16410 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
16420 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
16430 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
16440 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
16450 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
16460 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
16470 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
16480 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
16490 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
164a0 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63   quotes) in plac
164b0 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69  e of the %Q opti
164c0 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  on.  So, for exa
164d0 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
164e0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
164f0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
16500 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
16510 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
16520 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
16530 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
16540 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
16550 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
16560 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
16570 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
16580 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
16590 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
165a0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
165b0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
165c0 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
165d0 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
165e0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
165f0 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
16600 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
16610 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
16620 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
16630 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
16640 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73  exactly like "%s
16650 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  " with the.** ad
16660 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
16670 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
16680 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
16690 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
166a0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
166b0 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
166c0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
166d0 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a  t string. {END}.
166e0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
166f0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 33 7d  :.**.** {H17403}
16700 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
16710 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73  printf()] and [s
16720 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
16730 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
16740 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
16750 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72  n either pointer
16760 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
16770 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
16780 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20  gs held in.**   
16790 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f          memory o
167a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
167b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
167c0 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  or NULL pointers
167d0 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
167e0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
167f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61  te3_malloc()] fa
16800 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34  ils..**.** {H174
16810 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  06}  The [sqlite
16820 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e  3_snprintf()] in
16830 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 61  terface writes a
16840 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
16850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55 54  .**           UT
16860 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20  F-8 string into 
16870 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74  the buffer point
16880 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ed to by the sec
16890 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
168a0 20 20 20 20 20 20 20 20 20 20 20 70 72 6f 76 69             provi
168b0 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69 72  ded that the fir
168c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
168d0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
168e0 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 37  o..**.** {H17407
168f0 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
16900 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  snprintf()] inte
16910 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77  rface does not w
16920 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a  rite slots of.**
16930 20 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6f             its o
16940 75 74 70 75 74 20 62 75 66 66 65 72 20 28 74 68  utput buffer (th
16950 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16960 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 65 20  er) outside the 
16970 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  range.**        
16980 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20     of 0 through 
16990 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73 20  N-1 (where N is 
169a0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
169b0 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  ter).**         
169c0 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20    regardless of 
169d0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
169e0 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  e string.**     
169f0 20 20 20 20 20 20 72 65 71 75 65 73 74 65 64 20        requested 
16a00 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70  by the format sp
16a10 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a  ecification..*/.
16a20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
16a30 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
16a40 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
16a50 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
16a60 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
16a70 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
16a80 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
16a90 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
16aa0 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  r*, ...);../*.**
16ab0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
16ac0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
16ad0 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30 7d 20  system {H17300} 
16ae0 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20000>.**.** T
16af0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20  he SQLite core  
16b00 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
16b10 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
16b20 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
16b30 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
16b40 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
16b50 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
16b60 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
16b70 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
16b80 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
16b90 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
16ba0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
16bb0 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
16bc0 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
16bd0 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
16be0 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
16bf0 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
16c00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
16c10 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
16c20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
16c30 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
16c40 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
16c50 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
16c60 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
16c70 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
16c80 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  ** If sqlite3_ma
16c90 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
16ca0 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
16cb0 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
16cc0 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
16cd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
16ce0 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74    If the paramet
16cf0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
16d00 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
16d10 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
16d20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
16d30 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
16d40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
16d50 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73  .**.** Calling s
16d60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
16d70 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
16d80 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
16d90 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
16da0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
16db0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
16dc0 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
16dd0 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
16de0 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
16df0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72    The sqlite3_fr
16e00 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
16e10 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
16e20 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
16e30 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
16e40 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
16e50 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
16e60 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
16e70 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
16e80 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
16e90 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
16ea0 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
16eb0 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
16ec0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
16ed0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
16ee0 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
16ef0 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
16f00 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
16f10 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
16f20 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
16f30 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
16f40 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
16f50 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
16f60 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
16f70 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
16f80 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
16f90 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
16fa0 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
16fb0 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
16fc0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
16fd0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
16fe0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  alloc()..**.** T
16ff0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
17000 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
17010 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
17020 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
17030 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
17040 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
17050 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
17060 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
17070 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
17080 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
17090 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
170a0 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
170b0 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74  parameter.  If t
170c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
170d0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
170e0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
170f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
17100 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
17110 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
17120 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
17130 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
17140 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
17150 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
17160 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17170 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f  ..** If the seco
17180 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
17190 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
171a0 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
171b0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
171c0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
171d0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
171e0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
171f0 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
17200 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
17210 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
17220 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17230 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  ..** sqlite3_rea
17240 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
17250 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
17260 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
17270 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
17280 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
17290 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
172a0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
172b0 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49  navailable..** I
172c0 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
172d0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
172e0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
172f0 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
17300 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
17310 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
17320 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
17330 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
17340 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
17350 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17360 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
17370 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
17380 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  ed..** If sqlite
17390 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
173a0 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
173b0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
173c0 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
173d0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  eed..**.** The m
173e0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
173f0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
17400 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
17410 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
17420 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
17430 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
17440 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45  yte boundary. {E
17450 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  ND}.**.** The de
17460 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61  fault implementa
17470 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f  tion of the memo
17480 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
17490 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20  bsystem uses.** 
174a0 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  the malloc(), re
174b0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
174c0 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  () provided by t
174d0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
174e0 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38  brary..** {H1738
174f0 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53  2} However, if S
17500 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
17510 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
17520 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45  LITE_MEMORY_SIZE
17530 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72  =<i>NNN</i> C pr
17540 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
17550 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f   (where <i>NNN</
17560 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65  i>.** is an inte
17570 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74  ger), then SQLit
17580 65 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69  e create a stati
17590 63 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65  c array of at le
175a0 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69  ast.** <i>NNN</i
175b0 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  > bytes in size 
175c0 61 6e 64 20 75 73 65 73 20 74 68 61 74 20 61 72  and uses that ar
175d0 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  ray for all of i
175e0 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65  ts dynamic.** me
175f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
17600 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64  needs. {END}  Ad
17610 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20  ditional memory 
17620 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e  allocator option
17630 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65  s.** may be adde
17640 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
17650 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  ases..**.** In S
17660 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
17670 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
17680 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
17690 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
176a0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
176b0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
176c0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
176d0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
176e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
176f0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
17700 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
17710 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
17720 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
17730 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
17740 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
17750 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
17760 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  be used..**.** T
17770 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
17780 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
17790 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  lls.** the syste
177a0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
177b0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
177c0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
177d0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
177e0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
177f0 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
17800 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
17810 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
17820 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
17830 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
17840 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
17850 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
17860 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
17870 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65  rors are detecte
17880 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61  d, but.** they a
17890 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
178a0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
178b0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
178c0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
178d0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
178e0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  OMEM]..**.** INV
178f0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
17900 48 31 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71  H17303}  The [sq
17910 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
17920 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
17930 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e  ns either a poin
17940 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
17950 20 20 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63      a newly chec
17960 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66  ked-out block of
17970 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
17980 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  s of memory.**  
17990 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73           that is
179a0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c   8-byte aligned,
179b0 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e   or it returns N
179c0 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61  ULL if it is una
179d0 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
179e0 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20   to fulfill the 
179f0 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b  request..**.** {
17a00 48 31 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71  H17304}  The [sq
17a10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
17a20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
17a30 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
17a40 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r if.**         
17a50 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e    N is less than
17a60 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
17a70 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 35  o..**.** {H17305
17a80 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
17a90 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61  free(P)] interfa
17aa0 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f  ce releases memo
17ab0 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  ry previously.**
17ac0 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
17ad0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
17ae0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
17af0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17b00 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
17b10 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c   making it avail
17b20 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a  able for reuse..
17b30 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 36 7d 20 20  **.** {H17306}  
17b40 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
17b50 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69  e3_free(NULL)] i
17b60 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
17b70 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31  op..**.** {H1731
17b80 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  0}  A call to [s
17b90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30  qlite3_realloc(0
17ba0 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65  ,N)] is equivale
17bb0 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20  nt to a call.** 
17bc0 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71            to [sq
17bd0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
17be0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 32 7d  ..**.** {H17312}
17bf0 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
17c00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30  ite3_realloc(P,0
17c10 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  )] is equivalent
17c20 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20   to a call.**   
17c30 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69          to [sqli
17c40 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a  te3_free(P)]..**
17c50 0a 2a 2a 20 7b 48 31 37 33 31 35 7d 20 20 54 68  .** {H17315}  Th
17c60 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
17c70 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  es [sqlite3_mall
17c80 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
17c90 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20  realloc()],.**  
17ca0 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71           and [sq
17cb0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f  lite3_free()] fo
17cc0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d  r all of its mem
17cd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ory allocation a
17ce0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  nd.**           
17cf0 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  deallocation nee
17d00 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31  ds..**.** {H1731
17d10 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  8}  The [sqlite3
17d20 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69  _realloc(P,N)] i
17d30 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
17d40 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65   either a pointe
17d50 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  r.**           t
17d60 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65  o a block of che
17d70 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20  cked-out memory 
17d80 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
17d90 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20  tes in size.**  
17da0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73           that is
17db0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c   8-byte aligned,
17dc0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
17dd0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32  er..**.** {H1732
17de0 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  1}  When [sqlite
17df0 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20  3_realloc(P,N)] 
17e00 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55  returns a non-NU
17e10 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66  LL pointer, it f
17e20 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  irst.**         
17e30 20 20 63 6f 70 69 65 73 20 74 68 65 20 66 69 72    copies the fir
17e40 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f  st K bytes of co
17e50 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74  ntent from P int
17e60 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20  o the newly.**  
17e70 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74           allocat
17e80 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20  ed block, where 
17e90 4b 20 69 73 20 74 68 65 20 6c 65 73 73 65 72 20  K is the lesser 
17ea0 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a  of N and the siz
17eb0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
17ec0 20 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a    the buffer P..
17ed0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 32 7d 20 20  **.** {H17322}  
17ee0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  When [sqlite3_re
17ef0 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75  alloc(P,N)] retu
17f00 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  rns a non-NULL p
17f10 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74  ointer, it first
17f20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
17f30 6c 65 61 73 65 73 20 74 68 65 20 62 75 66 66 65  leases the buffe
17f40 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  r P..**.** {H173
17f50 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74  23}  When [sqlit
17f60 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
17f70 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
17f80 68 65 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a  he buffer P is.*
17f90 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20  *           not 
17fa0 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65  modified or rele
17fb0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  ased..**.** ASSU
17fc0 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
17fd0 41 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69  A17350}  The poi
17fe0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
17ff0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
18000 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
18010 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20  realloc()].**   
18020 20 20 20 20 20 20 20 20 6d 75 73 74 20 62 65 20          must be 
18030 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
18040 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
18050 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
18060 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
18070 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
18080 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18090 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
180a0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
180b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e  e.**           n
180c0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
180d0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37  ased..**.** {A17
180e0 33 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63  351}  The applic
180f0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
18100 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
18110 20 70 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20   part of.**     
18120 20 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66        a block of
18130 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
18140 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
18150 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
18160 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66        [sqlite3_f
18170 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
18180 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
18190 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
181a0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
181b0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
181c0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
181d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
181e0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
181f0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
18200 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
18210 69 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20  istics {H17370} 
18220 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53  <S30210>.**.** S
18230 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
18240 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
18250 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
18260 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
18270 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
18280 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
18290 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
182a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
182b0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
182c0 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
182d0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
182e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
182f0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
18300 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
18310 2a 20 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b  * {H17371} The [
18320 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
18330 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
18340 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
18350 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20  r of bytes.**   
18360 20 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79         of memory
18370 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
18380 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
18390 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
183a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20  .**.** {H17373} 
183b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
183c0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
183d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
183e0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
183f0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
18400 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
18410 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
18420 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
18430 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ark.**          
18440 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a  was last reset..
18450 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54  **.** {H17374} T
18460 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
18470 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
18480 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
18490 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
184a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
184b0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
184c0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
184d0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65  **          adde
184e0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
184f0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
18500 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
18510 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  lloc()],.**     
18520 20 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65       but not ove
18530 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
18540 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
18550 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
18560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75  .**          rou
18570 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
18580 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
18590 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  y call..**.** {H
185a0 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72  17375} The memor
185b0 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
185c0 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
185d0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
185e0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  of.**          [
185f0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
18600 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
18610 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
18620 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
18630 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f     [sqlite3_memo
18640 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
18650 69 73 20 74 72 75 65 2e 20 20 54 68 65 20 76 61  is true.  The va
18660 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
18670 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c           by [sql
18680 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
18690 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
186a0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
186b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69  .**          pri
186c0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
186d0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
186e0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
186f0 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
18700 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
18710 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
18720 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
18730 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
18740 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
18750 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
18760 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32  tor {H17390} <S2
18770 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  0000>.**.** SQLi
18780 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
18790 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
187a0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
187b0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
187c0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
187d0 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
187e0 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
187f0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
18800 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
18810 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
18820 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
18830 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
18840 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
18850 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
18860 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
18870 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
18880 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
18890 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
188a0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
188b0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
188c0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
188d0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
188e0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
188f0 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  ** A call to thi
18900 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
18910 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
18920 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
18930 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er P..**.** The 
18940 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
18950 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
18960 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
18970 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
18980 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
18990 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
189a0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
189b0 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
189c0 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
189d0 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
189e0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
189f0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
18a00 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65  .** On all subse
18a10 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
18a20 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
18a30 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
18a40 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
18a50 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
18a60 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
18a70 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
18a80 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
18a90 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  hod..**.** INVAR
18aa0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
18ab0 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  7392} The [sqlit
18ac0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c  e3_randomness(N,
18ad0 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72  P)] interface wr
18ae0 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a  ites N bytes of.
18af0 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69 67 68  **          high
18b00 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
18b10 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
18b20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69  buffer P..*/.voi
18b30 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
18b40 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
18b50 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
18b60 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
18b70 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
18b80 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32  n Callbacks {H12
18b90 35 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a  500} <S70100>.**
18ba0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
18bb0 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74   registers a aut
18bc0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18bd0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
18be0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
18bf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
18c00 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
18c10 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
18c20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
18c30 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
18c40 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
18c50 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
18c60 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
18c70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
18c80 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
18c90 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
18ca0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
18cb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
18cc0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
18cd0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
18ce0 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20    At various.** 
18cf0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
18d00 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
18d10 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
18d20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
18d30 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
18d40 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
18d50 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18d60 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
18d70 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
18d80 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
18d90 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20  e allowed.  The 
18da0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18db0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
18dc0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
18dd0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
18de0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
18df0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
18e00 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
18e10 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
18e20 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
18e30 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
18e40 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
18e50 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
18e60 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
18e70 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
18e80 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
18e90 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
18ea0 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20   error.  If the 
18eb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18ec0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
18ed0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
18ee0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
18ef0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
18f00 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
18f10 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
18f20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18f30 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
18f40 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
18f50 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
18f60 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
18f70 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
18f80 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
18f90 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
18fa0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
18fb0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
18fc0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
18fd0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
18fe0 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63   ok.  When the c
18ff0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
19000 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
19010 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
19020 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
19030 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
19040 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
19050 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
19060 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
19070 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
19080 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
19090 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
190a0 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20 61 75  nied.  If the au
190b0 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73  thorizer code is
190c0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
190d0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
190e0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
190f0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
19100 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
19110 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
19120 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
19130 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
19140 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
19150 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
19160 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
19170 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
19180 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
19190 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
191a0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
191b0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
191c0 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
191d0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
191e0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
191f0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
19200 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
19210 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
19220 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
19230 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
19240 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19250 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
19260 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
19270 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
19280 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
19290 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
192a0 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  ce. The second p
192b0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
192c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
192d0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
192e0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
192f0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
19300 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
19310 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
19320 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
19330 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
19340 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
19350 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
19360 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
19370 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
19380 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
19390 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
193a0 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
193b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
193c0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e  orized..**.** An
193d0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
193e0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
193f0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
19400 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
19410 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
19420 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
19430 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
19440 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
19450 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
19460 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
19470 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
19480 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
19490 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
194a0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
194b0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
194c0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
194d0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
194e0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
194f0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
19500 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
19510 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
19520 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
19530 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
19540 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
19550 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
19560 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
19570 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
19580 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
19590 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
195a0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
195b0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
195c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
195d0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
195e0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
195f0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
19600 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
19610 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
19620 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
19630 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
19640 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
19650 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
19660 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
19670 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
19680 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
19690 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
196a0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
196b0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
196c0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
196d0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
196e0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
196f0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
19700 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
19710 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
19720 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
19730 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
19740 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
19750 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  orizer..**.** On
19760 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
19770 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
19780 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
19790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
197a0 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
197b0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
197c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
197d0 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
197e0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
197f0 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65 20  l.  Disable the 
19800 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
19810 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
19820 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
19830 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
19840 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
19850 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
19860 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
19870 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
19880 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
19890 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
198a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
198b0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
198c0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
198d0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
198e0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
198f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
19900 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19910 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
19920 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
19930 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
19940 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
19950 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
19960 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
19970 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   When [sqlite3_p
19980 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
19990 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
199a0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
199b0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
199c0 67 68 74 20 62 65 20 72 65 70 72 65 70 61 72 65  ght be reprepare
199d0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
199e0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
199f0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
19a00 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
19a10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
19a20 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
19a30 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
19a40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19a50 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
19a60 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
19a70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19a80 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
19a90 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
19aa0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
19ab0 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
19ac0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
19ad0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
19ae0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
19af0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
19b00 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
19b10 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
19b20 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
19b30 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
19b40 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
19b50 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20 54 68  *.** {H12501} Th
19b60 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
19b70 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29  uthorizer(D,...)
19b80 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
19b90 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20  sters a.**      
19ba0 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63      authorizer c
19bb0 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74  allback with dat
19bc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19bd0 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30   D..**.** {H1250
19be0 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  2} The authorize
19bf0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
19c00 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
19c10 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20  tements are.**  
19c20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 70 61          being pa
19c30 72 73 65 65 64 20 61 6e 64 20 63 6f 6d 70 69 6c  rseed and compil
19c40 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30  ed..**.** {H1250
19c50 33 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  3} If the author
19c60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
19c70 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20  turns any value 
19c80 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  other than.**   
19c90 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
19ca0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
19cb0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
19cc0 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20  DENY], then.**  
19cd0 20 20 20 20 20 20 20 20 74 68 65 20 61 70 70 6c          the appl
19ce0 69 63 61 74 69 6f 6e 20 69 6e 74 65 72 66 61 63  ication interfac
19cf0 65 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73  e call that caus
19d00 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
19d10 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19d20 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68  llback to run sh
19d30 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  all fail with an
19d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
19d50 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f  LITE_ERROR] erro
19d60 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70  r code and an ap
19d70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
19d80 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b  message..**.** {
19d90 48 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65  H12504} When the
19da0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19db0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
19dc0 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70  LITE_OK], the op
19dd0 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  eration.**      
19de0 20 20 20 20 64 65 73 63 72 69 62 65 64 20 69 73      described is
19df0 20 70 72 6f 63 65 73 73 65 64 20 6e 6f 72 6d 61   processed norma
19e00 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  lly..**.** {H125
19e10 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74  05} When the aut
19e20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19e30 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
19e40 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20  _DENY], the.**  
19e50 20 20 20 20 20 20 20 20 61 70 70 6c 69 63 61 74          applicat
19e60 69 6f 6e 20 69 6e 74 65 72 66 61 63 65 20 63 61  ion interface ca
19e70 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 20 74  ll that caused t
19e80 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  he.**          a
19e90 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19ea0 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20  ck to run shall 
19eb0 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  fail.**         
19ec0 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45   with an [SQLITE
19ed0 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f  _ERROR] error co
19ee0 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20  de and an error 
19ef0 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20  message.**      
19f00 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74      explaining t
19f10 68 61 74 20 61 63 63 65 73 73 20 69 73 20 64 65  hat access is de
19f20 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  nied..**.** {H12
19f30 35 30 36 7d 20 49 66 20 74 68 65 20 61 75 74 68  506} If the auth
19f40 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65  orizer code (the
19f50 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
19f60 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
19f70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
19f80 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54  lback) is [SQLIT
19f90 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20  E_READ] and the 
19fa0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19fb0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ack returns.**  
19fc0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
19fd0 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68  IGNORE], then th
19fe0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
19ff0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
1a000 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ted to.**       
1a010 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c     insert a NULL
1a020 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
1a030 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
1a040 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
1a050 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ave.**          
1a060 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
1a070 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
1a080 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  n returned..**.*
1a090 2a 20 7b 48 31 32 35 30 37 7d 20 49 66 20 74 68  * {H12507} If th
1a0a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  e authorizer cod
1a0b0 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d  e (the 2nd param
1a0c0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1a0d0 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20  orizer.**       
1a0e0 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20     callback) is 
1a0f0 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74  anything other t
1a100 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  han [SQLITE_READ
1a110 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  ], then.**      
1a120 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20      a return of 
1a130 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1a140 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66  has the same eff
1a150 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44  ect as [SQLITE_D
1a160 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ENY]..**.** {H12
1a170 35 31 30 7d 20 54 68 65 20 66 69 72 73 74 20 70  510} The first p
1a180 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1a190 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1a1a0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
1a1b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1a1c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
1a1d0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1a1e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1a1f0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
1a200 0a 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54 68 65  .** {H12511} The
1a210 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a220 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1a230 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  k is an integer.
1a240 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
1a250 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1a260 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1a270 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69  cifies the parti
1a280 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20  cular action.** 
1a290 20 20 20 20 20 20 20 20 20 74 6f 20 62 65 20 61           to be a
1a2a0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1a2b0 20 7b 48 31 32 35 31 32 7d 20 54 68 65 20 74 68   {H12512} The th
1a2c0 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
1a2d0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1a2e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
1a2f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
1a300 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1a310 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1a320 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64  n.**          ad
1a330 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
1a340 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
1a350 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1a360 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32  ed..**.** {H1252
1a370 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  0} Each call to 
1a380 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1a390 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72  horizer()] overr
1a3a0 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ides.**         
1a3b0 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
1a3c0 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72  installed author
1a3d0 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  izer..**.** {H12
1a3e0 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68  521} A NULL auth
1a3f0 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61  orizer means tha
1a400 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69  t no authorizati
1a410 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  on.**          c
1a420 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1a430 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32  ed..**.** {H1252
1a440 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 61  2} The default a
1a450 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c  uthorizer is NUL
1a460 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
1a470 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1a480 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1a490 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1a4a0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1a4b0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1a4c0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1a4d0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1a4e0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1a4f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1a500 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1a510 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20   Codes {H12590} 
1a520 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12500>.**.** T
1a530 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1a540 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1a550 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1a560 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
1a570 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
1a580 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
1a590 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
1a5a0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
1a5b0 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
1a5c0 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
1a5d0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
1a5e0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
1a5f0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
1a600 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1a610 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1a620 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
1a630 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1a640 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1a650 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a660 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
1a670 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
1a680 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
1a690 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
1a6a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
1a6b0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
1a6c0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
1a6d0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
1a6e0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
1a6f0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1a700 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
1a710 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30   {H12550} <H1250
1a720 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0>.**.** The [sq
1a730 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1a740 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1a750 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1a760 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1a770 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1a780 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1a790 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1a7a0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1a7b0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1a7c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1a7d0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1a7e0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1a7f0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1a800 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1a810 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1a820 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1a830 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1a840 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1a850 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1a860 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1a870 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1a880 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1a890 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1a8a0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1a8b0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1a8c0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1a8d0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1a8e0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1a8f0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1a900 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1a910 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1a920 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1a930 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1a940 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1a950 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1a960 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
1a970 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1a980 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
1a990 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1a9a0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1a9b0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
1a9c0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
1a9d0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1a9e0 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72  le.  The 6th par
1a9f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1aa00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1aa10 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1aa20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1aa30 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1aa40 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1aa50 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1aa60 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1aa70 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1aa80 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1aa90 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1aaa0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1aab0 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e  L code..**.** IN
1aac0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1aad0 7b 48 31 32 35 35 31 7d 20 54 68 65 20 73 65 63  {H12551} The sec
1aae0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1aaf0 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
1ab00 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1ab10 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1ab20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73  izer callback] s
1ab30 68 61 6c 6c 20 62 65 20 61 6e 20 69 6e 74 65 67  hall be an integ
1ab40 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  er.**          [
1ab50 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75  SQLITE_COPY | au
1ab60 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 74  thorizer code] t
1ab70 68 61 74 20 73 70 65 63 69 66 69 65 73 20 77 68  hat specifies wh
1ab80 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  at action.**    
1ab90 20 20 20 20 20 20 69 73 20 62 65 69 6e 67 20 61        is being a
1aba0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1abb0 20 7b 48 31 32 35 35 32 7d 20 54 68 65 20 33 72   {H12552} The 3r
1abc0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1abd0 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 20  ters to the.**  
1abe0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1abf0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1ac00 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  | authorization 
1ac10 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20 20  callback].**    
1ac20 20 20 20 20 20 20 73 68 61 6c 6c 20 62 65 20 70        shall be p
1ac30 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
1ac40 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
1ac50 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  hich.**         
1ac60 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1ac70 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d  authorizer code]
1ac80 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
1ac90 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1aca0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 33 7d  ..**.** {H12553}
1acb0 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
1acc0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  er to the.**    
1acd0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
1ace0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1acf0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1ad00 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 74 68  ack] shall be th
1ad10 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e name.**       
1ad20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61     of the databa
1ad30 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61  se (example: "ma
1ad40 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63  in", "temp", etc
1ad50 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1ad60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 34 7d  ..**.** {H12554}
1ad70 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74   The 6th paramet
1ad80 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  er to the.**    
1ad90 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
1ada0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1adb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1adc0 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 74 68  ack] shall be th
1add0 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e name.**       
1ade0 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d     of the inner-
1adf0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1ae00 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1ae10 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1ae20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 63 63           the acc
1ae30 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
1ae40 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
1ae50 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
1ae60 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 20  rectly from.**  
1ae70 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 76 65          top-leve
1ae80 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1ae90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aea0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aeb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1aec0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1aed0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1aee0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1aef0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1af00 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1af10 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1af20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1af30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1af40 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1af50 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1af60 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1af70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1af80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1af90 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1afa0 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1afb0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1afc0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1afd0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1afe0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1aff0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1b000 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1b010 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b020 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1b030 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1b040 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1b050 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1b060 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b070 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1b080 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1b090 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1b0a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b0b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b0c0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1b0d0 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1b0e0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1b0f0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1b100 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b110 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1b120 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1b130 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1b140 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b150 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b160 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1b170 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1b180 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1b190 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b1a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b1b0 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
1b1c0 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
1b1d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1b1e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b1f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b200 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
1b210 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
1b220 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b230 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b240 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b250 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
1b260 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
1b270 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1b280 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1b290 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b2a0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
1b2b0 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
1b2c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1b2d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b2e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b2f0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
1b300 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
1b310 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1b320 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1b330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b340 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
1b350 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
1b360 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1b370 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b380 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1b390 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
1b3a0 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
1b3b0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1b3c0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1b3d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1b3e0 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
1b3f0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
1b400 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1b410 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b420 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
1b430 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
1b440 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
1b450 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1b460 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b470 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
1b480 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
1b490 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
1b4a0 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
1b4b0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
1b4c0 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
1b4d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1b4e0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1b4f0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1b500 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1b510 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
1b520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
1b530 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1b540 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b550 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b560 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
1b570 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
1b580 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1b590 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b5a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b5b0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
1b5c0 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
1b5d0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b5e0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1b5f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b600 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
1b610 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
1b620 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
1b630 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b640 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b650 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
1b660 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
1b670 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1b680 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b690 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b6a0 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
1b6b0 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
1b6c0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1b6d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b6e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b6f0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
1b700 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
1b710 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1b720 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b740 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
1b750 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
1b760 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1b770 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b780 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b790 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
1b7a0 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
1b7b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1b7c0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1b7d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b7e0 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
1b7f0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
1b800 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1b810 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1b820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1b830 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
1b840 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
1b850 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
1b860 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
1b870 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
1b880 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
1b890 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
1b8a0 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
1b8b0 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
1b8c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
1b8d0 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
1b8e0 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
1b8f0 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
1b900 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1b910 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1b920 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31  ng Functions {H1
1b930 32 32 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2280} <S60400>.*
1b940 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
1b950 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1b960 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
1b970 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
1b980 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
1b990 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
1b9a0 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
1b9b0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
1b9c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1b9d0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
1b9e0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1b9f0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1ba00 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
1ba10 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
1ba20 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
1ba30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
1ba40 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
1ba50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1ba60 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
1ba70 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20  returns a UTF-8 
1ba80 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
1ba90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1baa0 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74  ext.** as the st
1bab0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
1bac0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20  gins executing. 
1bad0 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c   Additional call
1bae0 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61  backs occur.** a
1baf0 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
1bb00 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
1bb10 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
1bb20 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
1bb30 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
1bb40 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
1bb50 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
1bb60 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a  es the trigger..
1bb70 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
1bb80 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1bb90 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1bba0 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
1bbb0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
1bbc0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
1bbd0 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70  finishes.  The p
1bbe0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
1bbf0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
1bc00 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
1bc10 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
1bc20 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
1bc30 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
1bc40 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
1bc50 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
1bc60 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   run..**.** INVA
1bc70 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
1bc80 31 32 32 38 31 7d 20 54 68 65 20 63 61 6c 6c 62  12281} The callb
1bc90 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1bca0 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
1bcb0 74 65 33 5f 74 72 61 63 65 28 29 5d 20 0a 2a 2a  te3_trace()] .**
1bcc0 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
1bcd0 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20  be invoked.**   
1bce0 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20         whenever 
1bcf0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1bd00 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f   first begins to
1bd10 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20   execute and.** 
1bd20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65           wheneve
1bd30 72 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70  r a trigger subp
1bd40 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65 67  rogram first beg
1bd50 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a  ins to run..**.*
1bd60 2a 20 7b 48 31 32 32 38 32 7d 20 45 61 63 68 20  * {H12282} Each 
1bd70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1bd80 5f 74 72 61 63 65 28 29 5d 20 73 68 61 6c 6c 20  _trace()] shall 
1bd90 6f 76 65 72 72 69 64 65 20 74 68 65 20 70 72 65  override the pre
1bda0 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20  viously.**      
1bdb0 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74      registered t
1bdc0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  race callback..*
1bdd0 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d 20 41 20  *.** {H12283} A 
1bde0 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c 62  NULL trace callb
1bdf0 61 63 6b 20 73 68 61 6c 6c 20 64 69 73 61 62 6c  ack shall disabl
1be00 65 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e tracing..**.**
1be10 20 7b 48 31 32 32 38 34 7d 20 54 68 65 20 66 69   {H12284} The fi
1be20 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1be30 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61  the trace callba
1be40 63 6b 20 73 68 61 6c 6c 20 62 65 20 61 20 63 6f  ck shall be a co
1be50 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  py of.**        
1be60 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68    the pointer wh
1be70 69 63 68 20 77 61 73 20 74 68 65 20 33 72 64 20  ich was the 3rd 
1be80 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
1be90 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a  ite3_trace()]..*
1bea0 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54 68  *.** {H12285} Th
1beb0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1bec0 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
1bed0 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20  allback is a.** 
1bee0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1bef0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1bf00 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
1bf10 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65   the original te
1bf20 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  xt.**          o
1bf30 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
1bf40 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 61  ent as it was pa
1bf50 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74  ssed into [sqlit
1bf60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1bf70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1bf80 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20  the equivalent, 
1bf90 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e  or an SQL commen
1bfa0 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  t indicating the
1bfb0 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20   beginning.**   
1bfc0 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 69 67         of a trig
1bfd0 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a  ger subprogram..
1bfe0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20 54  **.** {H12287} T
1bff0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1c000 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1c010 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66  by [sqlite3_prof
1c020 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ile()] is invoke
1c030 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  d.**          as
1c040 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
1c050 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a  ent finishes..**
1c060 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20 54 68 65  .** {H12288} The
1c070 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1c080 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
1c090 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
1c0a0 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  py of.**        
1c0b0 20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65    the 3rd parame
1c0c0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1c0d0 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  profile()]..**.*
1c0e0 2a 20 7b 48 31 32 32 38 39 7d 20 54 68 65 20 73  * {H12289} The s
1c0f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1c100 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63  to the profile c
1c110 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20  allback is a.** 
1c120 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1c130 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1c140 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61  tring that conta
1c150 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65  ins the complete
1c160 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20   text of.**     
1c170 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 74 61       the SQL sta
1c180 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73  tement as it was
1c190 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73   processed by [s
1c1a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1c1b0 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  2()].**         
1c1c0 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
1c1d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39  nt..**.** {H1229
1c1e0 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 61 72  0} The third par
1c1f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72  ameter to the pr
1c200 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69  ofile callback i
1c210 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a  s an estimate.**
1c220 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
1c230 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73   number of nanos
1c240 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63  econds of wall-c
1c250 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72  lock time requir
1c260 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ed to.**        
1c270 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74    run the SQL st
1c280 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61  atement from sta
1c290 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f  rt to finish..*/
1c2a0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
1c2b0 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
1c2c0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
1c2d0 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
1c2e0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1c2f0 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
1c300 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
1c310 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
1c320 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
1c330 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
1c340 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
1c350 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
1c360 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
1c370 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c380 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
1c390 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30  allbacks {H12910
1c3a0 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
1c3b0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f   This routine co
1c3c0 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62  nfigures a callb
1c3d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74  ack function - t
1c3e0 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63  he.** progress c
1c3f0 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69  allback - that i
1c400 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
1c410 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
1c420 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61  ng.** running ca
1c430 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1c440 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
1c450 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a  3_step()] and.**
1c460 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1c470 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d  ble()].  An exam
1c480 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
1c490 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1c4a0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
1c4b0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
1c4c0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
1c4d0 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  ** If the progre
1c4e0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
1c4f0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1c500 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
1c510 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
1c520 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
1c530 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
1c540 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
1c550 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
1c560 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
1c570 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
1c580 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1c590 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ler must not do 
1c5a0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1c5b0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1c5c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c5d0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1c5e0 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
1c5f0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
1c600 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1c610 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1c620 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c630 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1c640 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1c650 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1c660 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1c670 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1c680 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1c690 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1c6a0 2a 20 7b 48 31 32 39 31 31 7d 20 54 68 65 20 63  * {H12911} The c
1c6b0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1c6c0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1c6d0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1c6e0 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20  handler().**    
1c6f0 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64        is invoked
1c700 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
1c710 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
1c720 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20  g calls to.**   
1c730 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1c740 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  step()]..**.** {
1c750 48 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67  H12912} The prog
1c760 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73  ress callback is
1c770 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
1c780 72 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61  r every N virtua
1c790 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61  l.**          ma
1c7a0 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77  chine opcodes, w
1c7b0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
1c7c0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
1c7d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1c7e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65   [sqlite3_progre
1c7f0 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61  ss_handler()] ca
1c800 6c 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72  ll that register
1c810 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
1c820 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66  he callback.  If
1c830 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
1c840 31 2c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  1, sqlite3_progr
1c850 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a  ess_handler().**
1c860 20 20 20 20 20 20 20 20 20 20 61 63 74 73 20 61            acts a
1c870 73 20 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67  s if a NULL prog
1c880 72 65 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64  ress handler had
1c890 20 62 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e   been specified.
1c8a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20  .**.** {H12913} 
1c8b0 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  The progress cal
1c8c0 6c 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20  lback itself is 
1c8d0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
1c8e0 65 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20  e third.**      
1c8f0 20 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20      argument to 
1c900 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1c910 5f 68 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a  _handler()..**.*
1c920 2a 20 7b 48 31 32 39 31 34 7d 20 54 68 65 20 66  * {H12914} The f
1c930 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
1c940 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  o sqlite3_progre
1c950 73 73 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20  ss_handler() is 
1c960 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f  a.**          vo
1c970 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  id pointer passe
1c980 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73  d to the progres
1c990 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  s callback.**   
1c9a0 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
1c9b0 65 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20  each time it is 
1c9c0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
1c9d0 48 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c  H12915} If a cal
1c9e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
1c9f0 65 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e  ep()] results in
1ca00 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70   fewer than N op
1ca10 63 6f 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  codes.**        
1ca20 20 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64    being executed
1ca30 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  , then the progr
1ca40 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ess callback is 
1ca50 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a  never invoked..*
1ca60 2a 0a 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45 76  *.** {H12916} Ev
1ca70 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ery call to [sql
1ca80 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1ca90 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20  ndler()].**     
1caa0 20 20 20 20 20 6f 76 65 72 77 72 69 74 65 73 20       overwrites 
1cab0 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72  any previously r
1cac0 65 67 69 73 74 65 72 65 64 20 70 72 6f 67 72 65  egistered progre
1cad0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  ss handler..**.*
1cae0 2a 20 7b 48 31 32 39 31 37 7d 20 49 66 20 74 68  * {H12917} If th
1caf0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1cb00 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  er callback is N
1cb10 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67  ULL then no prog
1cb20 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ress.**         
1cb30 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f   handler is invo
1cb40 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ked..**.** {H129
1cb50 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72  18} If the progr
1cb60 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
1cb70 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74  urns a result ot
1cb80 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e  her than 0, then
1cb90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1cba0 20 62 65 68 61 76 69 6f 72 20 69 73 20 61 20 69   behavior is a i
1cbb0 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  f [sqlite3_inter
1cbc0 72 75 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e  rupt()] had been
1cbd0 20 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20   called..**     
1cbe0 20 20 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f       <S30500>.*/
1cbf0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
1cc00 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
1cc10 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
1cc20 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
1cc30 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1cc40 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
1cc50 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
1cc60 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d  nection {H12700}
1cc70 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S40200>.**.** 
1cc80 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1cc90 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
1cca0 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73  tabase file whos
1ccb0 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20  e name is given 
1ccc0 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  by the.** filena
1ccd0 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65  me argument. The
1cce0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1ccf0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
1cd00 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
1cd10 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1cd20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1cd30 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
1cd40 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1cd50 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
1cd60 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
1cd70 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61  n16(). A [databa
1cd80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1cd90 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
1cda0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
1cdb0 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
1cdc0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
1cdd0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
1cde0 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
1cdf0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
1ce00 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
1ce10 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1ce20 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1ce30 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
1ce40 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
1ce50 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
1ce60 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
1ce70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
1ce80 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65  * object. If the
1ce90 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1cea0 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
1ceb0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
1cec0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
1ced0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
1cee0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
1cef0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1cf00 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
1cf10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1cf20 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
1cf30 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
1cf40 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
1cf50 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
1cf60 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
1cf70 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
1cf80 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a   of the error..*
1cf90 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
1cfa0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
1cfb0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1cfc0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
1cfd0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1cfe0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1cff0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
1d000 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
1d010 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1d020 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
1d030 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
1d040 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
1d050 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
1d060 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
1d070 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
1d080 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
1d090 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
1d0a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1d0b0 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
1d0c0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
1d0d0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
1d0e0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
1d0f0 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
1d100 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
1d110 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1d120 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
1d130 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
1d140 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
1d150 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
1d160 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
1d170 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
1d180 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
1d190 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
1d1a0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
1d1b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
1d1c0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
1d1d0 74 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  ter can take one
1d1e0 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
1d1f0 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
1d200 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
1d210 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
1d220 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1d230 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51  _NOMUTEX] or [SQ
1d240 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1d250 54 45 58 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a  TEX] flags:.**.*
1d260 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53  * <dl>.** <dt>[S
1d270 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1d280 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
1d290 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1d2a0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
1d2b0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
1d2c0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1d2d0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
1d2e0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1d2f0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1d300 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  >.**.** <dt>[SQL
1d310 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1d320 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1d330 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1d340 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1d350 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1d360 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
1d370 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
1d380 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
1d390 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1d3a0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1d3b0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
1d3c0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
1d3d0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
1d3e0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
1d3f0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
1d400 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a   returned.</dd>.
1d410 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54  **.** <dt>[SQLIT
1d420 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1d430 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
1d440 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
1d450 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1d460 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1d470 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1d480 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
1d490 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20  tes it if.** it 
1d4a0 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
1d4b0 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
1d4c0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
1d4d0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
1d4e0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1d4f0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1d500 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
1d510 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  >.** </dl>.**.**
1d520 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
1d530 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1d540 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
1d550 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
1d560 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
1d570 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20  wn above or one 
1d580 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69  of the combinati
1d590 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
1d5a0 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68  combined.** with
1d5b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1d5c0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53  N_NOMUTEX] or [S
1d5d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1d5e0 55 54 45 58 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20  UTEX] flags,.** 
1d5f0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1d600 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
1d610 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51  **.** If the [SQ
1d620 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1d630 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
1d640 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1d650 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1d660 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
1d670 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
1d680 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
1d690 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
1d6a0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
1d6b0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
1d6c0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1d6d0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
1d6e0 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   If the.** [SQLI
1d6f0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1d700 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
1d710 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1d720 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
1d730 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
1d740 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
1d750 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
1d760 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
1d770 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1d780 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
1d790 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1d7a0 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  -time..**.** If 
1d7b0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1d7c0 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
1d7d0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1d7e0 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
1d7f0 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
1d800 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
1d810 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73  onnection.  This
1d820 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1d830 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
1d840 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
1d850 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1d860 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
1d870 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1d880 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
1d890 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
1d8a0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
1d8b0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
1d8c0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
1d8d0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
1d8e0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1d8f0 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
1d900 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
1d910 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
1d920 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
1d930 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
1d940 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
1d950 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
1d960 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
1d970 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
1d980 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
1d990 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  ** If the filena
1d9a0 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
1d9b0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
1d9c0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1d9d0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
1d9e0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1d9f0 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76  ated.  This priv
1da00 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
1da10 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
1da20 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
1da30 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
1da40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1da50 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
1da60 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
1da70 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1da80 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
1da90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1daa0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
1dab0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
1dac0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
1dad0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1dae0 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
1daf0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1db00 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
1db10 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72 74  e.  If the fourt
1db20 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1db30 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1db40 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
1db50 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1db60 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
1db70 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
1db80 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
1db90 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
1dba0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
1dbb0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1dbc0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
1dbd0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1dbe0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
1dbf0 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
1dc00 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
1dc10 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
1dc20 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
1dc30 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
1dc40 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
1dc50 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
1dc60 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
1dc70 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
1dc80 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
1dc90 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
1dca0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
1dcb0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
1dcc0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1dcd0 2a 20 7b 48 31 32 37 30 31 7d 20 54 68 65 20 5b  * {H12701} The [
1dce0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1dcf0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1dd00 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ()], and.**     
1dd10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
1dd20 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
1dd30 63 65 73 20 63 72 65 61 74 65 20 61 20 6e 65 77  ces create a new
1dd40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
1dd50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1dd60 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  n] associated wi
1dd70 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
1dd80 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
1dd90 20 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72 20   given in their 
1dda0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1ddb0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 32 7d 20  .**.** {H12702} 
1ddc0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
1ddd0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
1dde0 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a  eted as UTF-8.**
1ddf0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b 73            for [s
1de00 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61  qlite3_open()] a
1de10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
1de20 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54  _v2()] and as UT
1de30 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20  F-16.**         
1de40 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1de50 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73  yte order for [s
1de60 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1de70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 33 7d  ..**.** {H12703}
1de80 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
1de90 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1dea0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1deb0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1dec0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1ded0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1dee0 32 28 29 5d 20 77 72 69 74 65 73 20 61 20 70 6f  2()] writes a po
1def0 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a  inter to a new.*
1df00 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
1df10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1df20 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a   into *ppDb..**.
1df30 2a 2a 20 7b 48 31 32 37 30 34 7d 20 54 68 65 20  ** {H12704} The 
1df40 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1df50 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1df60 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20  6()], and.**    
1df70 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
1df80 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
1df90 61 63 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  aces return [SQL
1dfa0 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63  ITE_OK] upon suc
1dfb0 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20  cess,.**        
1dfc0 20 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69    or an appropri
1dfd0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
1dfe0 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a   on failure..**.
1dff0 2a 2a 20 7b 48 31 32 37 30 36 7d 20 54 68 65 20  ** {H12706} The 
1e000 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63  default text enc
1e010 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20  oding for a new 
1e020 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64  database created
1e030 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
1e040 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
1e050 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1e060 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20  open_v2()] will 
1e070 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  be UTF-8..**.** 
1e080 7b 48 31 32 37 30 37 7d 20 54 68 65 20 64 65 66  {H12707} The def
1e090 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69  ault text encodi
1e0a0 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74  ng for a new dat
1e0b0 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73  abase created us
1e0c0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
1e0d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1e0e0 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  )] will be UTF-1
1e0f0 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 39  6..**.** {H12709
1e100 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  } The [sqlite3_o
1e110 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72 66  pen(F,D)] interf
1e120 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ace is equivalen
1e130 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  t to.**         
1e140 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1e150 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72  2(F,D,G,0)] wher
1e160 65 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  e the G paramete
1e170 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  r is.**         
1e180 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
1e190 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45  ADWRITE]|[SQLITE
1e1a0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a  _OPEN_CREATE]..*
1e1b0 2a 0a 2a 2a 20 7b 48 31 32 37 31 31 7d 20 49 66  *.** {H12711} If
1e1c0 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
1e1d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1e1e0 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63  n_v2(F,D,G,V)] c
1e1f0 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20  ontains the.**  
1e200 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
1e210 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
1e220 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68  EADONLY] then th
1e230 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1e240 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ened.**         
1e250 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c   for reading onl
1e260 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 32  y..**.** {H12712
1e270 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1e280 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1e290 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
1e2a0 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  )] contains the.
1e2b0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
1e2c0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
1e2d0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 74 68  EN_READWRITE] th
1e2e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1e2f0 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20  is opened.**    
1e300 20 20 20 20 20 20 72 65 61 64 69 6e 67 20 61 6e        reading an
1e310 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
1e320 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65  sible, or for re
1e330 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68  ading only if th
1e340 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  e.**          fi
1e350 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
1e360 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
1e370 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a  rating system..*
1e380 2a 0a 2a 2a 20 7b 48 31 32 37 31 33 7d 20 49 66  *.** {H12713} If
1e390 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
1e3a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1e3b0 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f  n_v2(F,D,G,V)] o
1e3c0 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  mits the.**     
1e3d0 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1e3e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1e3f0 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61  TE] and the data
1e400 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1e410 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f            previo
1e420 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65  usly exist, an e
1e430 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1e440 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 34 7d  ..**.** {H12714}
1e450 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
1e460 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1e470 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
1e480 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  ] contains the.*
1e490 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76  *          bit v
1e4a0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  alue [SQLITE_OPE
1e4b0 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68  N_CREATE] and th
1e4c0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
1e4d0 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  not.**          
1e4e0 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74  previously exist
1e4f0 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70  , then an attemp
1e500 74 20 69 73 20 6d 61 64 65 20 74 6f 20 63 72 65  t is made to cre
1e510 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ate and.**      
1e520 20 20 20 20 69 6e 69 74 69 61 6c 69 7a 65 20 74      initialize t
1e530 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a  he database..**.
1e540 2a 2a 20 7b 48 31 32 37 31 37 7d 20 49 66 20 74  ** {H12717} If t
1e550 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1e560 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1e570 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1e580 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
1e590 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
1e5a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1e5b0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1e5c0 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 2c  then an private,
1e5d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68  .**          eph
1e5e0 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72  emeral, in-memor
1e5f0 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72  y database is cr
1e600 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
1e610 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20  nnection..**    
1e620 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53        <todo>Is S
1e630 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1e640 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  E|SQLITE_OPEN_RE
1e650 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64  ADWRITE required
1e660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
1e670 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1e680 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  )?</todo>.**.** 
1e690 7b 48 31 32 37 31 39 7d 20 49 66 20 74 68 65 20  {H12719} If the 
1e6a0 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c  filename is NULL
1e6b0 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72   or an empty str
1e6c0 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
1e6d0 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ate,.**         
1e6e0 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69   ephemeral on-di
1e6f0 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
1e700 20 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20   be created..** 
1e710 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49           <todo>I
1e720 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  s SQLITE_OPEN_CR
1e730 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e  EATE|SQLITE_OPEN
1e740 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69  _READWRITE requi
1e750 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
1e760 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  in sqlite3_open_
1e770 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  v2()?</todo>.**.
1e780 2a 2a 20 7b 48 31 32 37 32 31 7d 20 54 68 65 20  ** {H12721} The 
1e790 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1e7a0 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62 79  tion] created by
1e7b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1e7c0 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20  2(F,D,G,V)].**  
1e7d0 20 20 20 20 20 20 20 20 77 69 6c 6c 20 75 73 65          will use
1e7e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1e7f0 73 5d 20 6f 62 6a 65 63 74 20 69 64 65 6e 74 69  s] object identi
1e800 66 69 65 64 20 62 79 20 74 68 65 20 56 20 70 61  fied by the V pa
1e810 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20 20 20 20  rameter,.**     
1e820 20 20 20 20 20 6f 72 20 74 68 65 20 64 65 66 61       or the defa
1e830 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1e840 5d 20 6f 62 6a 65 63 74 20 69 66 20 56 20 69 73  ] object if V is
1e850 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1e860 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 33 7d 20  .**.** {H12723} 
1e870 54 77 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f  Two [database co
1e880 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20  nnections] will 
1e890 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63  share a common c
1e8a0 61 63 68 65 20 69 66 20 62 6f 74 68 20 77 65 72  ache if both wer
1e8b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70  e.**          op
1e8c0 65 6e 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ened with the sa
1e8d0 6d 65 20 56 46 53 20 77 68 69 6c 65 20 5b 73 68  me VFS while [sh
1e8e0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1e8f0 20 77 61 73 20 65 6e 61 62 6c 65 64 20 61 6e 64   was enabled and
1e900 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20  .**          if 
1e910 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65 73 20 63  both filenames c
1e920 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 75 73 69  ompare equal usi
1e930 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61 66 74 65  ng memcmp() afte
1e940 72 20 68 61 76 69 6e 67 20 62 65 65 6e 0a 2a 2a  r having been.**
1e950 20 20 20 20 20 20 20 20 20 20 70 72 6f 63 65 73            proces
1e960 73 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  sed by the [sqli
1e970 74 65 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c 50  te3_vfs | xFullP
1e980 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64 20  athname] method 
1e990 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a 2f 0a 69  of the VFS..*/.i
1e9a0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
1e9b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
1e9c0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1e9d0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1e9e0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
1e9f0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
1ea00 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1ea10 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1ea20 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1ea30 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
1ea40 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
1ea50 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1ea60 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
1ea70 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1ea80 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
1ea90 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1eaa0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
1eab0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1eac0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
1ead0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1eae0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1eaf0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
1eb00 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
1eb10 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1eb20 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1eb30 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
1eb40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
1eb50 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
1eb60 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
1eb70 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
1eb80 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
1eb90 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1eba0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
1ebb0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48   And Messages {H
1ebc0 31 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a  12800} <S60200>.
1ebd0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1ebe0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
1ebf0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1ec00 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
1ec10 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
1ec20 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1ec30 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1ec40 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
1ec50 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
1ec60 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
1ec70 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1ec80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
1ec90 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
1eca0 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
1ecb0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1ecc0 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
1ecd0 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
1ece0 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
1ecf0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1ed00 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 54  is undefined.  T
1ed10 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
1ed20 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
1ed30 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
1ed40 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
1ed50 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
1ed60 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
1ed70 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
1ed80 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
1ed90 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
1eda0 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
1edb0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  led..**.** The s
1edc0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
1edd0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
1ede0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
1edf0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
1ee00 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
1ee10 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
1ee20 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1ee30 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
1ee40 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f  ctively..** Memo
1ee50 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
1ee60 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
1ee70 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
1ee80 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
1ee90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1eea0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
1eeb0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
1eec0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
1eed0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
1eee0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
1eef0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
1ef00 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
1ef10 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
1ef20 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
1ef30 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
1ef40 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
1ef50 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
1ef60 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1ef70 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
1ef80 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
1ef90 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
1efa0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
1efb0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
1efc0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
1efd0 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
1efe0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
1eff0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
1f000 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
1f010 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
1f020 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
1f030 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
1f040 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
1f050 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
1f060 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
1f070 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
1f080 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
1f090 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
1f0a0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
1f0b0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
1f0c0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
1f0d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f0e0 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
1f0f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
1f100 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
1f110 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
1f120 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
1f130 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
1f140 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
1f150 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
1f160 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
1f170 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
1f180 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
1f190 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
1f1a0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
1f1b0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
1f1c0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
1f1d0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
1f1e0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
1f1f0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
1f200 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
1f210 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
1f220 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
1f230 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
1f240 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
1f250 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
1f260 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
1f270 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  et..**.** INVARI
1f280 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
1f290 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  801} The [sqlite
1f2a0 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e  3_errcode(D)] in
1f2b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1f2c0 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  the numeric.**  
1f2d0 20 20 20 20 20 20 20 20 5b 72 65 73 75 6c 74 20          [result 
1f2e0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
1f2f0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1f300 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
1f310 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ently.**        
1f320 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61    failed interfa
1f330 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  ce call associat
1f340 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1f350 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f360 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38  ] D..**.** {H128
1f370 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
1f380 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1f390 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(D)] interface 
1f3a0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
1f3b0 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ric.**          
1f3c0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1f3d0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
1f3e0 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20  ost recently.** 
1f3f0 20 20 20 20 20 20 20 20 20 66 61 69 6c 65 64 20           failed 
1f400 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61  interface call a
1f410 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1f420 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1f430 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
1f440 2a 20 7b 48 31 32 38 30 33 7d 20 54 68 65 20 5b  * {H12803} The [
1f450 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44  sqlite3_errmsg(D
1f460 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1f470 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20  errmsg16(D)].** 
1f480 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
1f490 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  ces return Engli
1f4a0 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
1f4b0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 0a   that describes.
1f4c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1f4d0 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73  error in the mos
1f4e0 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69  tly recently fai
1f4f0 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61  led interface ca
1f500 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ll,.**          
1f510 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74 68 65  encoded as eithe
1f520 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1f530 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
1f540 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54  **.** {H12807} T
1f550 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1f560 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1f570 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73  errmsg()] and [s
1f580 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1f590 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1f5a0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  re valid until t
1f5b0 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69  he next SQLite i
1f5c0 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a  nterface call..*
1f5d0 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43 61  *.** {H12808} Ca
1f5e0 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69  lls to API routi
1f5f0 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  nes that do not 
1f600 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20  return an error 
1f610 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
1f620 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69   (example: [sqli
1f630 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
1f640 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20  ]) do not.**    
1f650 20 20 20 20 20 20 63 68 61 6e 67 65 20 74 68 65        change the
1f660 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d   error code or m
1f670 65 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20  essage returned 
1f680 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  by.**          [
1f690 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1f6a0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  )], [sqlite3_ext
1f6b0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
1f6c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
1f6d0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1f6e0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  , or [sqlite3_er
1f6f0 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rmsg16()]..**.**
1f700 20 7b 48 31 32 38 30 39 7d 20 49 6e 74 65 72 66   {H12809} Interf
1f710 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f  aces that are no
1f720 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
1f730 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  h a specific.** 
1f740 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1f750 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
1f760 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20  examples:.**    
1f770 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
1f780 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71  printf()] or [sq
1f790 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1f7a0 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20  red_cache()].** 
1f7b0 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20           do not 
1f7c0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
1f7d0 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
1f7e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1f7f0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
1f800 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1f810 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
1f820 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1f830 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20  3_errmsg()], or 
1f840 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1f850 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
1f860 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
1f870 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
1f880 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1f890 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1f8a0 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
1f8b0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1f8c0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
1f8d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1f8e0 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
1f8f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1f900 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
1f910 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30  nt Object {H1300
1f920 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b  0} <H13010>.** K
1f930 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
1f940 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
1f950 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f960 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
1f970 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
1f980 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
1f990 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
1f9a0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
1f9b0 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
1f9c0 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
1f9d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f9e0 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
1f9f0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
1fa00 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
1fa10 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
1fa20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
1fa30 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
1fa40 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
1fa50 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
1fa60 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1fa70 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
1fa80 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1fa90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1faa0 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
1fab0 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
1fac0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
1fad0 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
1fae0 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
1faf0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1fb00 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
1fb10 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
1fb20 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
1fb30 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1fb40 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
1fb50 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
1fb60 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
1fb70 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1fb80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1fb90 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
1fba0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
1fbb0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
1fbc0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1fbd0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
1fbe0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1fbf0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1fc00 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
1fc10 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
1fc20 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
1fc30 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
1fc40 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
1fc50 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1fc60 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
1fc70 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
1fc80 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
1fc90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fca0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
1fcb0 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30  ts {H12760} <S20
1fcc0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
1fcd0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1fce0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
1fcf0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
1fd00 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
1fd10 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
1fd20 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
1fd30 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
1fd40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1fd50 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
1fd60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
1fd70 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
1fd80 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
1fd90 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1fda0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
1fdb0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
1fdc0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
1fdd0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
1fde0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
1fdf0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
1fe00 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
1fe10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1fe20 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
1fe30 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20  that construct. 
1fe40 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   The function re
1fe50 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69  turns the old li
1fe60 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  mit..**.** If th
1fe70 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
1fe80 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
1fe90 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
1fea0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72  nchanged..** For
1feb0 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67   the limit categ
1fec0 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49  ory of SQLITE_LI
1fed0 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73  MIT_XYZ there is
1fee0 20 61 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a   a hard upper.**
1fef0 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20   bound set by a 
1ff00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70  compile-time C p
1ff10 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ff20 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d  o named SQLITE_M
1ff30 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20  AX_XYZ..** (The 
1ff40 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
1ff50 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
1ff60 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a   to "_MAX_".).**
1ff70 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63   Attempts to inc
1ff80 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
1ff90 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
1ffa0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
1ffb0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
1ffc0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
1ffd0 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a  pper limit..**.*
1ffe0 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74  * Run time limit
1fff0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
20000 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
20010 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
20020 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
20030 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
20040 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
20050 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
20060 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
20070 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
20080 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
20090 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
200a0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
200b0 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72   a.** webbrowser
200c0 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
200d0 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
200e0 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
200f0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
20100 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
20110 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
20120 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
20130 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
20140 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
20150 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
20160 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
20170 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
20180 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
20190 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
201a0 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
201b0 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
201c0 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
201d0 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
201e0 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
201f0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
20200 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
20210 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
20220 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
20230 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
20240 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
20250 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
20260 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
20270 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
20280 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
20290 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
202a0 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
202b0 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
202c0 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
202d0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
202e0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
202f0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
20300 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
20310 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
20320 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
20330 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
20340 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
20350 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20 41 20 73  .** {H12762} A s
20360 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
20370 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  o [sqlite3_limit
20380 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56  (D,C,V)] where V
20390 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
203a0 70 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65 73  positive changes
203b0 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68   the limit on th
203c0 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72  e size of constr
203d0 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20  uct C in the.** 
203e0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
203f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
20400 20 74 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f   to the lesser o
20410 66 20 56 20 61 6e 64 20 74 68 65 20 68 61 72 64  f V and the hard
20420 20 75 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20   upper.**       
20430 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20     bound on the 
20440 73 69 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69  size of C that i
20450 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  s set at compile
20460 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  -time..**.** {H1
20470 32 37 36 36 7d 20 41 20 73 75 63 63 65 73 73 66  2766} A successf
20480 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
20490 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29  te3_limit(D,C,V)
204a0 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e 65 67  ] where V is neg
204b0 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
204c0 20 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61    leaves the sta
204d0 74 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  te of the [datab
204e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
204f0 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  D unchanged..**.
20500 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41 20 73 75  ** {H12769} A su
20510 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
20520 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
20530 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20  D,C,V)] returns 
20540 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
20550 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
20560 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f  it on the size o
20570 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e  f construct C in
20580 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
20590 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
205a0 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77  ction] D as it w
205b0 61 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  as prior to the 
205c0 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  call..*/.int sql
205d0 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
205e0 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
205f0 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
20600 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
20610 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
20620 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48  ries {H12790} <H
20630 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  12760>.** KEYWOR
20640 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
20650 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65  ory} {limit cate
20660 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
20670 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
20680 66 69 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70  fine various asp
20690 65 63 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62  ects of a [datab
206a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
206b0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
206c0 69 6d 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62  imited in size b
206d0 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  y calls to [sqli
206e0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
206f0 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   The meanings of
20700 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
20710 69 74 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f  its are as follo
20720 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ws:.**.** <dl>.*
20730 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
20740 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
20750 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
20760 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
20770 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
20780 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a  table row.<dd>.*
20790 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
207a0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
207b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
207c0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
207d0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
207e0 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
207f0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
20800 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
20810 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20820 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
20830 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
20840 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
20850 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
20860 6f 66 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74  of a SELECT or t
20870 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
20880 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
20890 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
208a0 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
208b0 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
208c0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
208d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
208e0 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
208f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20900 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
20910 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
20920 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
20930 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
20940 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
20950 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
20960 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20970 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
20980 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
20990 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
209a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
209b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
209c0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
209d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
209e0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
209f0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
20a00 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
20a10 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
20a20 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
20a30 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
20a40 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
20a50 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
20a60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20a70 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
20a80 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
20a90 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a   function.</dd>.
20aa0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
20ab0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
20ac0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20ad0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
20ae0 66 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  f attached datab
20af0 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ases.</dd>.**.**
20b00 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
20b10 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
20b20 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
20b30 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
20b40 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
20b50 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
20b60 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47  the LIKE or.** G
20b70 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  LOB operators.</
20b80 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
20b90 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
20ba0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
20bb0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
20bc0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72  um number of var
20bd0 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c  iables in an SQL
20be0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
20bf0 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e  can.** be bound.
20c00 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
20c10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20c20 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
20c30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20c40 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
20c50 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
20c60 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
20c70 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
20c80 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
20c90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20ca0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
20cb0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
20cc0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
20cd0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
20ce0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
20cf0 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
20d00 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
20d10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
20d20 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
20d30 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
20d40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
20d50 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
20d60 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
20d70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
20d80 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
20d90 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
20da0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
20db0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
20dc0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
20dd0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
20de0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
20df0 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a            9../*.
20e00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
20e10 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
20e20 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d  atement {H13010}
20e30 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59   <S10000>.** KEY
20e40 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
20e50 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
20e60 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
20e70 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
20e80 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
20e90 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
20ea0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
20eb0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
20ec0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
20ed0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
20ee0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
20ef0 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
20f00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
20f10 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
20f20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73  prior call to [s
20f30 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
20f40 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
20f50 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
20f60 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
20f70 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
20f80 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
20f90 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
20fa0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
20fb0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
20fc0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
20fd0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
20fe0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
20ff0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21000 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
21010 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
21020 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
21030 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
21040 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21050 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
21060 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79  **.** If the nBy
21070 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
21080 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
21090 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
210a0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
210b0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
210c0 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73  tor. If nByte is
210d0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
210e0 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
210f0 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20  ximum.** number 
21100 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66  of  bytes read f
21110 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20  rom zSql.  When 
21120 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
21130 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
21140 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
21150 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
21160 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
21170 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
21180 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d  or.** the nByte-
21190 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
211a0 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
211b0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
211c0 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ows.** that the 
211d0 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
211e0 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
211f0 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  d, then there is
21200 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66   a small.** perf
21210 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
21220 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62  e to be gained b
21230 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
21240 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
21250 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f  t.** is equal to
21260 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
21270 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
21280 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
21290 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
212a0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
212b0 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a  bytes..**.** *pz
212c0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
212d0 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
212e0 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65  st byte past the
212f0 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66   end of the.** f
21300 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
21310 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
21320 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
21330 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
21340 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  st.** statement 
21350 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
21360 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
21370 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d  ting to what rem
21380 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c  ains.** uncompil
21390 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d  ed..**.** *ppStm
213a0 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
213b0 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
213c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
213d0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
213e0 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
213f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
21400 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20  p()].  If there 
21410 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
21420 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
21430 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20  o NULL.  If the 
21440 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
21450 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
21460 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
21470 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
21480 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
21490 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
214a0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31   to NULL..** {A1
214b0 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e  3018} The callin
214c0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
214d0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
214e0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
214f0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
21500 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
21510 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
21520 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
21530 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
21540 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
21550 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
21560 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72   returned, other
21570 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
21580 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
21590 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
215a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
215b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
215c0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
215d0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
215e0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
215f0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
21600 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
21610 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
21620 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
21630 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
21640 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
21650 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
21660 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76  ed..** In the "v
21670 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
21680 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
21690 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
216a0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
216b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
216c0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
216d0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
216e0 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
216f0 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
21700 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
21710 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
21720 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66  .** behave a dif
21730 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20  ferently in two 
21740 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
21750 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74  .** <li>.** If t
21760 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
21770 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
21780 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
21790 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
217a0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
217b0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
217c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
217d0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
217e0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
217f0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
21800 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
21810 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65  t again.  If the
21820 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e   schema has chan
21830 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20  ged in.** a way 
21840 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73  that makes the s
21850 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67  tatement no long
21860 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74  er valid, [sqlit
21870 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
21880 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20  still.** return 
21890 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e  [SQLITE_SCHEMA].
218a0 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65    But unlike the
218b0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
218c0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
218d0 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61  ] is.** now a fa
218e0 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c  tal error.  Call
218f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
21900 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e  pare_v2()] again
21910 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74   will not make t
21920 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61  he.** error go a
21930 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20  way.  Note: use 
21940 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
21950 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  )] to find the t
21960 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61  ext.** of the pa
21970 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74  rsing error that
21980 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b   results in an [
21990 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72  SQLITE_SCHEMA] r
219a0 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  eturn..** </li>.
219b0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68  **.** <li>.** Wh
219c0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
219d0 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
219e0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
219f0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
21a00 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
21a10 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
21a20 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
21a30 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68    The legacy beh
21a40 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
21a50 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
21a60 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
21a70 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
21a80 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
21a90 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
21aa0 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20   you would have 
21ab0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
21ac0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
21ad0 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72  3_reset()] in or
21ae0 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74  der.** to find t
21af0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
21b00 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
21b10 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
21b20 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
21b30 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
21b40 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
21b50 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
21b60 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
21b70 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
21b80 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e  * </ol>.**.** IN
21b90 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
21ba0 7b 48 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71  {H13011} The [sq
21bb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62  lite3_prepare(db
21bc0 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a  ,zSql,...)] and.
21bd0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
21be0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21bf0 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e  db,zSql,...)] in
21c00 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72  terfaces interpr
21c10 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
21c20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72     text in their
21c30 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20   zSql parameter 
21c40 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  as UTF-8..**.** 
21c50 7b 48 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71  {H13012} The [sq
21c60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
21c70 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e  db,zSql,...)] an
21c80 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
21c90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
21ca0 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  _v2(db,zSql,...)
21cb0 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74  ] interfaces int
21cc0 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20  erpret the.**   
21cd0 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74         text in t
21ce0 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65  heir zSql parame
21cf0 74 65 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ter as UTF-16 in
21d00 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
21d10 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48   order..**.** {H
21d20 31 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42  13013} If the nB
21d30 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  yte argument to 
21d40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21d50 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74  _v2(db,zSql,nByt
21d60 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  e,...)].**      
21d70 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69      and its vari
21d80 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74 68 61  ants is less tha
21d90 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c 20  n zero, the SQL 
21da0 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20  text is.**      
21db0 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53      read from zS
21dc0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
21dd0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
21de0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
21df0 2a 20 7b 48 31 33 30 31 34 7d 20 49 66 20 74 68  * {H13014} If th
21e00 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
21e10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
21e20 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
21e30 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  nByte,...)].**  
21e40 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20          and its 
21e50 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d  variants is non-
21e60 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
21e70 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79  t most nBytes by
21e80 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  tes of.**       
21e90 20 20 20 53 51 4c 20 74 65 78 74 20 69 73 20 72     SQL text is r
21ea0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a  ead from zSql..*
21eb0 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49 6e  *.** {H13015} In
21ec0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21ed0 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50  e_v2(db,zSql,N,P
21ee0 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74  ,pzTail)] and it
21ef0 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20  s variants.**   
21f00 20 20 20 20 20 20 20 69 66 20 74 68 65 20 7a 53         if the zS
21f10 71 6c 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  ql input text co
21f20 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e  ntains more than
21f30 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65   one SQL stateme
21f40 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  nt.**          a
21f50 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  nd pzTail is not
21f60 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54   NULL, then *pzT
21f70 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
21f80 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20  oint to the.**  
21f90 20 20 20 20 20 20 20 20 66 69 72 73 74 20 62 79          first by
21fa0 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  te past the end 
21fb0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
21fc0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
21fd0 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ql..**          
21fe0 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20  <todo>What does 
21ff0 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f  *pzTail point to
22000 20 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65   if there is one
22010 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64   statement?</tod
22020 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 36  o>.**.** {H13016
22030 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
22040 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
22050 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
22060 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29  ql,N,ppStmt,...)
22070 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
22080 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
22090 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f  ants writes into
220a0 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74   *ppStmt a point
220b0 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20  er to a new.**  
220c0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
220d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
220e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c  a pointer to NUL
220f0 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69  L if zSql contai
22100 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ns.**          n
22110 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  othing other tha
22120 6e 20 77 68 69 74 65 73 70 61 63 65 20 6f 72 20  n whitespace or 
22130 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  comments..**.** 
22140 7b 48 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71  {H13019} The [sq
22150 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
22160 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
22170 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 72  d its variants r
22180 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
22190 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72    [SQLITE_OK] or
221a0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
221b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
221c0 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  n failure..**.**
221d0 20 7b 48 31 33 30 32 31 7d 20 42 65 66 6f 72 65   {H13021} Before
221e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
221f0 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  e(db,zSql,nByte,
22200 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20  ppStmt,pzTail)] 
22210 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  or its.**       
22220 20 20 20 76 61 72 69 61 6e 74 73 20 72 65 74 75     variants retu
22230 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e  rns an error (an
22240 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
22250 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c  an [SQLITE_OK]),
22260 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
22270 79 20 66 69 72 73 74 20 73 65 74 20 2a 70 70 53  y first set *ppS
22280 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  tmt to NULL..*/.
22290 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
222a0 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
222b0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
222c0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
222d0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
222e0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
222f0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
22300 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
22310 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
22320 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
22330 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
22340 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
22350 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
22360 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
22370 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
22380 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
22390 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
223a0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
223b0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
223c0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
223d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
223e0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
223f0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
22400 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
22410 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
22420 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
22430 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
22440 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
22450 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
22460 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
22470 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
22480 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
22490 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
224a0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
224b0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
224c0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
224d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
224e0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
224f0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
22500 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
22510 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
22520 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
22530 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
22540 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
22550 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
22560 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
22570 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
22580 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
22590 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
225a0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
225b0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
225c0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
225d0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
225e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
225f0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
22600 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
22610 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
22620 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
22630 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
22640 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
22650 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
22660 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
22670 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
22680 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
22690 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
226a0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
226b0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
226c0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
226d0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
226e0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
226f0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
22700 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
22710 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
22720 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
22730 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
22740 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
22750 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
22760 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
22770 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
22780 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
22790 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
227a0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
227b0 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
227c0 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
227d0 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30  L {H13100} <H130
227e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  00>.**.** This i
227f0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
22800 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
22810 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
22820 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
22830 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
22840 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
22850 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22860 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  if that statemen
22870 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  t was.** compile
22880 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
22890 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
228a0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
228b0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
228c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
228d0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31  NTS:.**.** {H131
228e0 30 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70  01} If the [prep
228f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22900 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72  passed as the ar
22910 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20  gument to.**    
22920 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
22930 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c  ql()] was compil
22940 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
22950 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22960 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  _v2()] or.**    
22970 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
22980 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20  repare16_v2()], 
22990 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71  then [sqlite3_sq
229a0 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20  l()] returns.** 
229b0 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74           a point
229c0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
229d0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63  minated string c
229e0 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d  ontaining a UTF-
229f0 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20  8 rendering.**  
22a00 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f          of the o
22a10 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74  riginal SQL stat
22a20 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ement..**.** {H1
22a30 33 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72  3102} If the [pr
22a40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22a50 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  ] passed as the 
22a60 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20  argument to.**  
22a70 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
22a80 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70  _sql()] was comp
22a90 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
22aa0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
22ab0 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  re()] or.**     
22ac0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
22ad0 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e  epare16()], then
22ae0 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d   [sqlite3_sql()]
22af0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
22b00 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  pointer..**.** {
22b10 48 31 33 31 30 33 7d 20 54 68 65 20 73 74 72 69  H13103} The stri
22b20 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ng returned by [
22b30 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20  sqlite3_sql(S)] 
22b40 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
22b50 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
22b60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22b70 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64  nt] S is deleted
22b80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
22b90 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f  finalize(S)]..*/
22ba0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
22bb0 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
22bc0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
22bd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22be0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
22bf0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b  d Value Object {
22c00 48 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e  H15000} <S20200>
22c10 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
22c20 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
22c30 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
22c40 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
22c50 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
22c60 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
22c70 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
22c80 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
22c90 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
22ca0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
22cb0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
22cc0 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
22cd0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
22ce0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
22cf0 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73  t stores. Values
22d00 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
22d10 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
22d20 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
22d30 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
22d40 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
22d50 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
22d60 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
22d70 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
22d80 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
22d90 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
22da0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
22db0 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
22dc0 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
22dd0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
22de0 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
22df0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
22e00 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
22e10 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
22e20 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
22e30 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
22e40 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
22e50 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
22e60 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
22e70 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
22e80 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
22e90 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
22ea0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
22eb0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
22ec0 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
22ed0 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
22ee0 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
22ef0 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
22f00 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
22f10 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  A internal mutex
22f20 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
22f30 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
22f40 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
22f50 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
22f60 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
22f70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
22f80 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
22f90 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
22fa0 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
22fb0 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
22fc0 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
22fd0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
22fe0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
22ff0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
23000 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
23010 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
23020 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
23030 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
23040 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
23050 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
23060 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
23070 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
23080 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
23090 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
230a0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
230b0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
230c0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
230d0 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
230e0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
230f0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
23100 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
23110 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
23120 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
23130 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
23140 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
23150 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
23160 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
23170 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  ween between pro
23180 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
23190 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
231a0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
231b0 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
231c0 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
231d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
231e0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
231f0 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
23200 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
23210 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
23220 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
23230 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
23240 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
23250 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
23260 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
23270 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
23280 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
23290 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
232a0 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
232b0 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
232c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
232d0 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
232e0 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
232f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
23300 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
23310 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
23320 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  ue()]..** The [s
23330 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
23340 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
23350 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
23360 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
23370 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
23380 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
23390 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
233a0 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
233b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
233c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
233d0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
233e0 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31  ntext Object {H1
233f0 36 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6001} <S20200>.*
23400 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
23410 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
23420 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
23430 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
23440 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
23450 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41  ntext object.  A
23460 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
23470 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
23480 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
23490 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
234a0 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
234b0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
234c0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
234d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
234e0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
234f0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
23500 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
23510 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
23520 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
23530 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
23540 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
23550 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
23560 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
23570 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
23580 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
23590 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
235a0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
235b0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
235c0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
235d0 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
235e0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
235f0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
23600 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
23610 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
23620 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
23630 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
23640 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
23650 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33   Statements {H13
23660 35 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  500} <S70300>.**
23670 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
23680 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
23690 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
236a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
236b0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
236c0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
236d0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
236e0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
236f0 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  ding}.**.** In t
23700 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69  he SQL strings i
23710 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
23720 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
23730 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
23740 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
23750 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
23760 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f  a parameter in o
23770 6e 65 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d  ne of these form
23780 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
23790 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
237a0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
237b0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
237c0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
237d0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
237e0 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  In the parameter
237f0 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f   forms shown abo
23800 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74  ve NNN is an int
23810 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
23820 20 61 6e 64 20 56 56 56 20 69 73 20 61 6e 20 61   and VVV is an a
23830 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72  lpha-numeric par
23840 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 68 65  ameter name. The
23850 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
23860 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
23870 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
23880 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
23890 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
238a0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
238b0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
238c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
238d0 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
238e0 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  d here..**.** Th
238f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
23900 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
23910 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
23920 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
23930 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
23940 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
23950 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
23960 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
23970 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
23980 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
23990 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
239a0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
239b0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
239c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
239d0 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66   set..** The lef
239e0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
239f0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
23a00 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65   of 1.  When the
23a10 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
23a20 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
23a30 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
23a40 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
23a50 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
23a60 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
23a70 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
23a80 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
23a90 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e  rence..** The in
23aa0 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
23ab0 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
23ac0 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
23ad0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
23ae0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
23af0 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
23b00 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64  esired.  The ind
23b10 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
23b20 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
23b30 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
23b40 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75  .** The NNN valu
23b50 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
23b60 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
23b70 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
23b80 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
23b90 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
23ba0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
23bb0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
23bc0 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
23bd0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
23be0 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
23bf0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
23c00 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72  **.** In those r
23c10 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
23c20 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
23c30 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
23c40 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
23c50 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
23c60 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
23c70 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
23c80 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
23c90 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
23ca0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
23cb0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
23cc0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
23cd0 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
23ce0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
23cf0 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67  gative, the leng
23d00 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
23d10 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
23d20 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
23d30 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
23d40 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
23d50 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 67 75  * The fifth argu
23d60 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
23d70 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
23d80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
23d90 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
23da0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
23db0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
23dc0 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
23dd0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
23de0 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
23df0 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
23e00 64 20 77 69 74 68 20 69 74 2e 20 49 66 20 74 68  d with it. If th
23e10 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
23e20 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
23e30 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
23e40 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
23e50 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
23e60 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
23e70 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
23e80 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
23e90 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
23ea0 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
23eb0 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66  d..** If the fif
23ec0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
23ed0 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
23ee0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
23ef0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
23f00 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
23f10 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
23f20 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
23f30 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
23f40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
23f50 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
23f60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
23f70 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
23f80 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
23f90 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
23fa0 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
23fb0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
23fc0 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75  s.  A zeroblob u
23fd0 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
23fe0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
23ff0 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
24000 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
24010 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
24020 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
24030 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
24040 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
24050 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
24060 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
24070 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
24080 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
24090 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
240a0 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
240b0 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
240c0 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
240d0 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
240e0 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
240f0 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
24100 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
24110 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24120 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
24130 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
24140 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71  led after.** [sq
24150 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
24160 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72  ()] (and its var
24170 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74  iants) or [sqlit
24180 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a  e3_reset()] and.
24190 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74  ** before [sqlit
241a0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42  e3_step()]..** B
241b0 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
241c0 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
241d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
241e0 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62   routine..** Unb
241f0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
24200 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
24210 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  as NULL..**.** T
24220 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
24230 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
24240 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
24250 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a  n error code if.
24260 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  ** anything goes
24270 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45   wrong.  [SQLITE
24280 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
24290 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
242a0 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
242b0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
242c0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
242d0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
242e0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
242f0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
24300 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
24310 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74  ed if these rout
24320 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
24330 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20  on a.** virtual 
24340 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20  machine that is 
24350 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20  the wrong state 
24360 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72  or which has alr
24370 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69  eady been finali
24380 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f  zed..** Detectio
24390 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75  n of misuse is u
243a0 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c  nreliable.  Appl
243b0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
243c0 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  not depend.** on
243d0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72   SQLITE_MISUSE r
243e0 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f  eturns.  SQLITE_
243f0 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64  MISUSE is intend
24400 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61  ed to indicate a
24410 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f  .** a logic erro
24420 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61  r in the applica
24430 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65  tion.  Future ve
24440 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
24450 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20   might.** panic 
24460 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75  rather than retu
24470 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
24480 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
24490 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
244a0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
244b0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
244c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
244d0 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
244e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
244f0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
24500 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
24510 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54  **.** {H13506} T
24520 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e  he [SQL statemen
24530 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f  t compiler] reco
24540 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66  gnizes tokens of
24550 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20   the forms.**   
24560 20 20 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e         "?", "?NN
24570 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56  N", "$VVV", ":VV
24580 56 22 2c 20 61 6e 64 20 22 40 56 56 56 22 20 61  V", and "@VVV" a
24590 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  s SQL parameters
245a0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  ,.**          wh
245b0 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73  ere NNN is any s
245c0 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f  equence of one o
245d0 72 20 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a  r more digits.**
245e0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68            and wh
245f0 65 72 65 20 56 56 56 20 69 73 20 61 6e 79 20 73  ere VVV is any s
24600 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f  equence of one o
24610 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65  r more alphanume
24620 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ric.**          
24630 63 68 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a  characters or ":
24640 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f  :" optionally fo
24650 6c 6c 6f 77 65 64 20 62 79 20 61 20 73 74 72 69  llowed by a stri
24660 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a  ng containing.**
24670 20 20 20 20 20 20 20 20 20 20 6e 6f 20 73 70 61            no spa
24680 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65  ces and containe
24690 64 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68  d within parenth
246a0 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  eses..**.** {H13
246b0 35 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c  509} The initial
246c0 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c   value of an SQL
246d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
246e0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31  LL..**.** {H1351
246f0 32 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20  2} The index of 
24700 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d  an "?" SQL param
24710 65 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67  eter is one larg
24720 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20  er than the.**  
24730 20 20 20 20 20 20 20 20 6c 61 72 67 65 73 74 20          largest 
24740 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72  index of SQL par
24750 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65  ameter to the le
24760 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20  ft, or 1 if.**  
24770 20 20 20 20 20 20 20 20 74 68 65 20 22 3f 22 20          the "?" 
24780 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20  is the leftmost 
24790 53 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  SQL parameter..*
247a0 2a 0a 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54 68  *.** {H13515} Th
247b0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f  e index of an "?
247c0 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74  NNN" SQL paramet
247d0 65 72 20 69 73 20 74 68 65 20 69 6e 74 65 67 65  er is the intege
247e0 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  r NNN..**.** {H1
247f0 33 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20  3518} The index 
24800 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24  of an ":VVV", "$
24810 56 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20  VVV", or "@VVV" 
24820 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
24830 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
24840 20 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64   same as the ind
24850 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f  ex of leftmost o
24860 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20 74 68  ccurrences of th
24870 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
24880 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72     parameter, or
24890 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74   one more than t
248a0 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78  he largest index
248b0 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20   over all.**    
248c0 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 73        parameters
248d0 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20   to the left if 
248e0 74 68 69 73 20 69 73 20 74 68 65 20 66 69 72 73  this is the firs
248f0 74 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20  t occurrence.** 
24900 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 69 73           of this
24910 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31   parameter, or 1
24920 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20   if this is the 
24930 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74  leftmost paramet
24940 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32  er..**.** {H1352
24950 31 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74  1} The [SQL stat
24960 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20  ement compiler] 
24970 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 5b 53  fails with an [S
24980 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20  QLITE_RANGE].** 
24990 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 69           error i
249a0 66 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  f the index of a
249b0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
249c0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a  is less than 1.*
249d0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 67 72  *          or gr
249e0 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 63  eater than the c
249f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49  ompile-time SQLI
24a00 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f  TE_MAX_VARIABLE_
24a10 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20 20  NUMBER.**       
24a20 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a     parameter..**
24a30 0a 2a 2a 20 7b 48 31 33 35 32 34 7d 20 43 61 6c  .** {H13524} Cal
24a40 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
24a50 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74  ind_text | sqlit
24a60 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e  e3_bind(S,N,V,..
24a70 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
24a80 61 73 73 6f 63 69 61 74 65 20 74 68 65 20 76 61  associate the va
24a90 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53  lue V with all S
24aa0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68 61  QL parameters ha
24ab0 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20  ving an.**      
24ac0 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69      index of N i
24ad0 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
24ae0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a  statement] S..**
24af0 0a 2a 2a 20 7b 48 31 33 35 32 37 7d 20 43 61 6c  .** {H13527} Cal
24b00 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
24b10 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74  ind_text | sqlit
24b20 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29  e3_bind(S,N,...)
24b30 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76  ].**          ov
24b40 65 72 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c  erride prior cal
24b50 6c 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ls with the same
24b60 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64   values of S and
24b70 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33   N..**.** {H1353
24b80 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61  0} Bindings esta
24b90 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69  blished by [sqli
24ba0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20  te3_bind_text | 
24bb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e  sqlite3_bind(S,.
24bc0 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
24bd0 20 70 65 72 73 69 73 74 20 61 63 72 6f 73 73 20   persist across 
24be0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
24bf0 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a  3_reset(S)]..**.
24c00 2a 2a 20 7b 48 31 33 35 33 33 7d 20 49 6e 20 63  ** {H13533} In c
24c10 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
24c20 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56  _bind_blob(S,N,V
24c30 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,L,D)],.**      
24c40 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
24c50 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
24c60 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
24c70 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
24c80 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
24c90 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73  D)] SQLite binds
24ca0 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20   the first L.** 
24cb0 20 20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f           bytes o
24cc0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
24cd0 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
24ce0 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20  by V, when L.** 
24cf0 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d           is non-
24d00 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
24d10 7b 48 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c  {H13536} In call
24d20 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
24d30 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
24d40 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  D)] or.**       
24d50 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
24d60 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
24d70 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73  D)] SQLite binds
24d80 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20   characters.**  
24d90 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74          from V t
24da0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
24db0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 20   zero character 
24dc0 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69  when L is negati
24dd0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33  ve..**.** {H1353
24de0 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  9} In calls to [
24df0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
24e00 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a  b(S,N,V,L,D)],.*
24e10 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
24e20 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
24e30 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  N,V,L,D)], or.**
24e40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
24e50 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
24e60 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20  ,N,V,L,D)] when 
24e70 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  D is the special
24e80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
24e90 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54  stant [SQLITE_ST
24ea0 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73  ATIC], SQLite as
24eb0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 76  sumes that the v
24ec0 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20  alue V.**       
24ed0 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74     is held in st
24ee0 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73  atic unmanaged s
24ef0 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e  pace that will n
24f00 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20  ot change.**    
24f10 20 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65        during the
24f20 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65   lifetime of the
24f30 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   binding..**.** 
24f40 7b 48 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c  {H13542} In call
24f50 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
24f60 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c  nd_blob(S,N,V,L,
24f70 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
24f80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
24f90 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  ext(S,N,V,L,D)],
24fa0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
24fb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
24fc0 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  xt16(S,N,V,L,D)]
24fd0 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73   when D is the s
24fe0 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20  pecial.**       
24ff0 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c     constant [SQL
25000 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
25010 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65  the routine make
25020 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
25030 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
25040 74 68 65 20 76 61 6c 75 65 20 56 20 62 65 66 6f  the value V befo
25050 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
25060 2a 0a 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e  *.** {H13545} In
25070 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
25080 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e  e3_bind_blob(S,N
25090 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,L,D)],.**    
250a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
250b0 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
250c0 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
250d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
250e0 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c  nd_text16(S,N,V,
250f0 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20  L,D)] when D is 
25100 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
25110 20 20 20 20 20 20 20 20 20 61 20 66 75 6e 63 74           a funct
25120 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f  ion, SQLite invo
25130 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f  kes that functio
25140 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65  n to destroy the
25150 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
25160 75 65 20 56 20 61 66 74 65 72 20 69 74 20 68 61  ue V after it ha
25170 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
25180 20 74 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a   the value V..**
25190 0a 2a 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e 20  .** {H13548} In 
251a0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
251b0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
251c0 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61  S,N,V,L)] the va
251d0 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20  lue bound.**    
251e0 20 20 20 20 20 20 69 73 20 61 20 42 4c 4f 42 20        is a BLOB 
251f0 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61  of L bytes, or a
25200 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
25210 42 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69  B if L is negati
25220 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35  ve..**.** {H1355
25230 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  1} In calls to [
25240 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
25250 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56  ue(S,N,V)] the V
25260 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a   argument may.**
25270 20 20 20 20 20 20 20 20 20 20 62 65 20 65 69 74            be eit
25280 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64  her a [protected
25290 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
252a0 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20  object or an.** 
252b0 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74           [unprot
252c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
252d0 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  lue] object..*/.
252e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
252f0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
25300 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
25310 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
25320 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
25330 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
25340 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
25350 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
25360 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
25370 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
25380 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
25390 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
253a0 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
253b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
253c0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
253d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
253e0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
253f0 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
25400 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
25410 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25420 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
25430 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, 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 74 65 78 74 31 36 28  te3_bind_text16(
25460 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
25470 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
25480 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
25490 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
254a0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
254b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
254c0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
254d0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
254e0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
254f0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
25500 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
25510 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25520 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
25530 72 61 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30  rameters {H13600
25540 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
25550 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61   This routine ca
25560 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
25570 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
25580 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
25590 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
255a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
255b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
255c0 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
255d0 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
255e0 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
255f0 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
25600 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
25610 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
25620 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
25630 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
25640 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
25650 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
25660 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
25670 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  me..**.** This r
25680 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
25690 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
256a0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
256b0 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
256c0 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
256d0 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
256e0 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
256f0 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
25700 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
25710 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
25720 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
25730 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65   of the ?NNN are
25740 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
25750 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
25760 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53  he list..**.** S
25770 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
25780 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
25790 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
257a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
257b0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
257c0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
257d0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
257e0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
257f0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
25800 2a 20 7b 48 31 33 36 30 31 7d 20 54 68 65 20 5b  * {H13601} The [
25810 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
25820 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d  ameter_count(S)]
25830 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25840 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ns.**          t
25850 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78  he largest index
25860 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61   of all SQL para
25870 6d 65 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a  meters in the.**
25880 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
25890 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
258a0 2c 20 6f 72 20 30 20 69 66 20 53 20 63 6f 6e 74  , or 0 if S cont
258b0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61  ains no SQL para
258c0 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73  meters..*/.int s
258d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
258e0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
258f0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
25900 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
25910 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
25920 6d 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20 3c  meter {H13620} <
25930 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S70300>.**.** Th
25940 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
25950 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
25960 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
25970 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72  n-th.** [SQL par
25980 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72  ameter] in a [pr
25990 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
259a0 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ]..** SQL parame
259b0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
259c0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
259d0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
259e0 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
259f0 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
25a00 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
25a10 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
25a20 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
25a30 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
25a40 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
25a50 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
25a60 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
25a70 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
25a80 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
25a90 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61   the name..** Pa
25aa0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
25ab0 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
25ac0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
25ad0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
25ae0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73  e.** and are als
25af0 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  o referred to as
25b00 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
25b10 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54  meters"..**.** T
25b20 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
25b30 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
25b40 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
25b50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76  ..**.** If the v
25b60 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66  alue n is out of
25b70 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
25b80 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   n-th parameter 
25b90 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
25ba0 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
25bb0 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75  urned.  The retu
25bc0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
25bd0 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
25be0 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
25bf0 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
25c00 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
25c10 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
25c20 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
25c30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25c40 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
25c50 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
25c60 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
25c70 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
25c80 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
25c90 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
25ca0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25cb0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
25cc0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
25cd0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
25ce0 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
25cf0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
25d00 7b 48 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71  {H13621} The [sq
25d10 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25d20 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  eter_name(S,N)] 
25d30 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
25d40 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  s.**          a 
25d50 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
25d60 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  of the name of t
25d70 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
25d80 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   in.**          
25d90 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25da0 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e  atement] S havin
25db0 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a  g index N, or.**
25dc0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69            NULL i
25dd0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51  f there is no SQ
25de0 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68  L parameter with
25df0 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74   index N or if t
25e00 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  he.**          p
25e10 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e  arameter with in
25e20 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e  dex N is an anon
25e30 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20  ymous parameter 
25e40 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  "?"..*/.const ch
25e50 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
25e60 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
25e70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
25e80 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
25e90 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
25ea0 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
25eb0 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31  A Given Name {H1
25ec0 33 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3640} <S70300>.*
25ed0 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
25ee0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
25ef0 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
25f00 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a  its name.  The.*
25f10 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
25f20 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
25f30 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
25f40 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
25f50 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
25f60 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
25f70 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20  te3_bind()].  A 
25f80 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
25f90 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
25fa0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
25fb0 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61  found.  The para
25fc0 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
25fd0 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
25fe0 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
25ff0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
26000 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
26010 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
26020 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
26030 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
26040 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
26050 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
26060 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
26070 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
26080 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26090 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
260a0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
260b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
260c0 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ex()]..**.** INV
260d0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
260e0 48 31 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c  H13641} The [sql
260f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
26100 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20  ter_index(S,N)] 
26110 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
26120 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
26130 65 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70  e index of SQL p
26140 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
26150 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26160 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ent].**         
26170 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61   S whose name ma
26180 74 63 68 65 73 20 74 68 65 20 55 54 46 2d 38 20  tches the UTF-8 
26190 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69  string N, or 0 i
261a0 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 20  f there is.**   
261b0 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e         no match.
261c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
261d0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
261e0 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
261f0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
26200 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
26210 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
26220 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
26230 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
26240 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37  ent {H13660} <S7
26250 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74  0300>.**.** Cont
26260 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
26270 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
26280 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
26290 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
262a0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
262b0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
262c0 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
262d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
262e0 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75  .** Use this rou
262f0 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
26300 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
26310 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  s to NULL..**.**
26320 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
26330 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54 68 65 20  ** {H13661} The 
26340 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
26350 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65  indings(S)] inte
26360 72 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c  rface resets all
26370 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20   SQL.**         
26380 20 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69   parameter bindi
26390 6e 67 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70  ngs in the [prep
263a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
263b0 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a  S back to NULL..
263c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
263d0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
263e0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
263f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
26400 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
26410 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
26420 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30   {H13710} <S1070
26430 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20  0>.**.** Return 
26440 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
26450 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
26460 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
26470 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
26480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
26490 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
264a0 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
264b0 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
264c0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
264d0 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
264e0 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
264f0 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
26500 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
26510 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54 68  *.** {H13711} Th
26520 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
26530 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65  n_count(S)] inte
26540 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
26550 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20  e number of.**  
26560 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20          columns 
26570 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
26580 74 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74  t generated by t
26590 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
265a0 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20  tement] S,.**   
265b0 20 20 20 20 20 20 20 6f 72 20 30 20 69 66 20 53         or 0 if S
265c0 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61   does not genera
265d0 74 65 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e  te a result set.
265e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
265f0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
26600 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
26610 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26620 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
26630 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
26640 20 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30   {H13720} <S1070
26650 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
26660 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
26670 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
26680 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
26690 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
266a0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
266b0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
266c0 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74  ment.  The sqlit
266d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
266e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
266f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
26700 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
26710 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
26720 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
26730 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
26740 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
26750 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
26760 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
26770 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66  6 string.  The f
26780 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
26790 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
267a0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
267b0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
267c0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
267d0 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64  ment. The second
267e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
267f0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
26800 65 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73  er.  The leftmos
26810 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
26820 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er 0..**.** The 
26830 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
26840 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
26850 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
26860 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
26870 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
26880 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
26890 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
268a0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
268b0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
268c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
268d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
268e0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
268f0 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
26900 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  .**.** If sqlite
26910 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
26920 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
26930 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
26940 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
26950 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
26960 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
26970 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
26980 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
26990 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
269a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
269b0 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
269c0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
269d0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
269e0 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
269f0 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
26a00 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
26a10 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
26a20 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
26a30 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
26a40 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
26a50 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
26a60 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
26a70 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
26a80 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
26a90 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49  he next..**.** I
26aa0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
26ab0 20 7b 48 31 33 37 32 31 7d 20 41 20 73 75 63 63   {H13721} A succ
26ac0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
26ad0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
26ae0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
26af0 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  N)].**          
26b00 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
26b10 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
26b20 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68  e Nth column (wh
26b30 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20  ere 0 is.**     
26b40 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73       the leftmos
26b50 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68  t column) for th
26b60 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
26b70 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
26b80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26b90 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f  ent] S as a zero
26ba0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
26bb0 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
26bc0 7b 48 31 33 37 32 33 7d 20 41 20 73 75 63 63 65  {H13723} A succe
26bd0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
26be0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
26bf0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53  _column_name16(S
26c00 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
26c10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
26c20 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ns the name of t
26c30 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77  he Nth column (w
26c40 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20  here 0 is.**    
26c50 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f        the leftmo
26c60 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74  st column) for t
26c70 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
26c80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
26c90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26ca0 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72  ment] S as a zer
26cb0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
26cc0 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  -16 string.**   
26cd0 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61         in the na
26ce0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
26cf0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20  .**.** {H13724} 
26d00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
26d10 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20  umn_name()] and 
26d20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26d30 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20  name16()].**    
26d40 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
26d50 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70   return a NULL p
26d60 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79 20 61  ointer if they a
26d70 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20  re unable to.** 
26d80 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74           allocat
26d90 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
26da0 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65   their normal re
26db0 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  turn strings..**
26dc0 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20 49 66 20  .** {H13725} If 
26dd0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
26de0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
26df0 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72  mn_name(S,N)] or
26e00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
26e10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
26e20 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74  e16(S,N)] is out
26e30 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20   of range, then 
26e40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
26e50 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72  interfaces retur
26e60 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
26e70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d  ..**.** {H13726}
26e80 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
26e90 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
26ea0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
26eb0 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  N)] and.**      
26ec0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
26ed0 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  umn_name16(S,N)]
26ee0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
26ef0 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20   the next.**    
26f00 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69        call to ei
26f10 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74  ther routine wit
26f20 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64  h the same S and
26f30 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a   N parameters.**
26f40 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74            or unt
26f50 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  il [sqlite3_fina
26f60 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c  lize(S)] is call
26f70 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32  ed..**.** {H1372
26f80 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74  7} When a result
26f90 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45   column of a [SE
26fa0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
26fb0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20  contains.**     
26fc0 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73       an AS claus
26fd0 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  e, the name of t
26fe0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  hat column is th
26ff0 65 20 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20  e identifier.** 
27000 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20           to the 
27010 72 69 67 68 74 20 6f 66 20 74 68 65 20 41 53 20  right of the AS 
27020 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73  keyword..*/.cons
27030 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
27040 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
27050 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
27060 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
27070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
27080 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
27090 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
270a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
270b0 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
270c0 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48   Query Result {H
270d0 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13740} <S10700>.
270e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
270f0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
27100 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
27110 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66  e what column of
27120 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69   what.** table i
27130 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65  n which database
27140 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b   a result of a [
27150 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
27160 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a  t comes from..**
27170 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
27180 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
27190 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
271a0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
271b0 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
271c0 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
271d0 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61  ng.  The _databa
271e0 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
271f0 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
27200 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
27210 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
27220 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
27230 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
27240 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
27250 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
27260 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65  umn name..** The
27270 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
27280 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
27290 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
272a0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
272b0 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
272c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
272d0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
272e0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
272f0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
27300 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
27310 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
27320 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73  .**.** The names
27330 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
27340 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
27350 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
27360 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
27370 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
27380 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  n..**.** The fir
27390 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
273a0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c  he following cal
273b0 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  ls is a [prepare
273c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
273d0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
273e0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
273f0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
27400 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
27410 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
27420 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
27430 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
27440 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
27450 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68  **.** If the Nth
27460 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
27470 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
27480 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
27490 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
274a0 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
274b0 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
274c0 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
274d0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
274e0 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20  ** NULL.  These 
274f0 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
27500 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
27510 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
27520 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
27530 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73  ccurs.  Otherwis
27540 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
27550 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
27560 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
27570 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63  , table.** and c
27580 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
27590 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
275a0 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
275b0 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68  m..**.** As with
275c0 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
275d0 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f  e APIs, those po
275e0 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36  stfixed with "16
275f0 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
27600 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
27610 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75  gs, the other fu
27620 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
27630 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  TF-8. {END}.**.*
27640 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65  * These APIs are
27650 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
27660 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
27670 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
27680 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
27690 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
276a0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
276b0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
276c0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  fined..**.** {A1
276d0 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20  3751}.** If two 
276e0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
276f0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
27700 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
27710 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
27720 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
27730 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
27740 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
27750 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
27760 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
27770 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
27780 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
27790 20 7b 48 31 33 37 34 31 7d 20 54 68 65 20 5b 73   {H13741} The [s
277a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
277b0 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29  tabase_name(S,N)
277c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
277d0 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
277e0 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38         the UTF-8
277f0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
27800 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
27810 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  abase from which
27820 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27830 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
27840 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  mn of the [prepa
27850 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
27860 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a   is extracted,.*
27870 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55  *          or NU
27880 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
27890 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67  lumn of S is a g
278a0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
278b0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
278c0 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
278d0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
278e0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
278f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20  .**.** {H13742} 
27900 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
27910 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
27920 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  e16(S,N)] interf
27930 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
27940 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
27950 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  he UTF-16 native
27960 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f   byte order zero
27970 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
27980 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
27990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f  .**          fro
279a0 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20  m which the Nth 
279b0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
279c0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
279d0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a  tatement] S is.*
279e0 2a 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61  *          extra
279f0 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66  cted, or NULL if
27a00 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
27a10 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
27a20 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  l expression.** 
27a30 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75           or if u
27a40 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
27a50 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72  e memory to stor
27a60 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
27a70 2a 20 7b 48 31 33 37 34 33 7d 20 54 68 65 20 5b  * {H13743} The [
27a80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27a90 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  able_name(S,N)] 
27aa0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27ab0 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
27ac0 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a       the UTF-8 z
27ad0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
27ae0 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ame of the table
27af0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a   from which the.
27b00 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
27b10 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
27b20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
27b30 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65  tatement] S is e
27b40 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20  xtracted,.**    
27b50 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66        or NULL if
27b60 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
27b70 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
27b80 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  l expression.** 
27b90 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75           or if u
27ba0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
27bb0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72  e memory to stor
27bc0 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
27bd0 2a 20 7b 48 31 33 37 34 34 7d 20 54 68 65 20 5b  * {H13744} The [
27be0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27bf0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  able_name16(S,N)
27c00 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
27c10 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
27c20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
27c30 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
27c40 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  der zero-termina
27c50 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
27c60 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20  table.**        
27c70 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65    from which the
27c80 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
27c90 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  mn of the [prepa
27ca0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
27cb0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
27cc0 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55  extracted, or NU
27cd0 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
27ce0 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67  lumn of S is a g
27cf0 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
27d00 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
27d10 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
27d20 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
27d30 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
27d40 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20  .**.** {H13745} 
27d50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
27d60 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
27d70 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
27d80 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
27d90 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55  *          the U
27da0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
27db0 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
27dc0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72   table column fr
27dd0 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  om which the.** 
27de0 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
27df0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
27e00 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27e10 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72  ement] S is extr
27e20 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20  acted,.**       
27e30 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68     or NULL if th
27e40 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
27e50 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65  S is a general e
27e60 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20  xpression.**    
27e70 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62        or if unab
27e80 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
27e90 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74  emory to store t
27ea0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  he name..**.** {
27eb0 48 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c  H13746} The [sql
27ec0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
27ed0 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  in_name16(S,N)] 
27ee0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27ef0 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
27f00 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
27f10 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
27f20 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  r zero-terminate
27f30 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
27f40 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
27f50 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63  column from whic
27f60 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  h the Nth result
27f70 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
27f80 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
27f90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27fa0 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20  S is extracted, 
27fb0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
27fc0 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20  th column.**    
27fd0 20 20 20 20 20 20 6f 66 20 53 20 69 73 20 61 20        of S is a 
27fe0 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
27ff0 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20  on or if unable 
28000 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
28010 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ry.**          t
28020 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
28030 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d  ..**.** {H13748}
28040 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
28050 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20  es from.**      
28060 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
28070 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
28080 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
28090 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
280a0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20  **          are 
280b0 76 61 6c 69 64 20 66 6f 72 20 74 68 65 20 6c 69  valid for the li
280c0 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70  fetime of the [p
280d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
280e0 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  t].**          o
280f0 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f  r until the enco
28100 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20  ding is changed 
28110 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64  by another metad
28120 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ata.**          
28130 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66  interface call f
28140 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72 65 70  or the same prep
28150 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
28160 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
28170 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
28180 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20 49 66 20  .** {A13751} If 
28190 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
281a0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
281b0 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  more.**         
281c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
281d0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
281e0 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
281f0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
28200 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65           for the
28210 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
28220 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
28230 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
28240 20 20 20 20 20 20 20 20 20 61 74 20 74 68 65 20           at the 
28250 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
28260 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
28270 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
28280 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28290 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
282a0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
282b0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
282c0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
282d0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
282e0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
282f0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
28300 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
28310 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
28320 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
28330 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
28340 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
28350 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
28360 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
28370 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
28380 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
28390 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
283a0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
283b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
283c0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
283d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
283e0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
283f0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
28400 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
28410 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33  uery Result {H13
28420 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  760} <S10700>.**
28430 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
28440 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
28450 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28460 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
28470 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
28480 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
28490 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
284a0 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
284b0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
284c0 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
284d0 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
284e0 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
284f0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
28500 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
28510 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
28520 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
28530 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
28540 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f  .  If the Nth co
28550 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
28560 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
28570 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
28580 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
28590 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
285a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  eturned..** The 
285b0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
285c0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
285d0 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a  encoded. {END}.*
285e0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
285f0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
28600 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
28610 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
28620 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
28630 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
28640 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
28650 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
28660 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
28670 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
28680 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
28690 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
286a0 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
286b0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
286c0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
286d0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
286e0 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
286f0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
28700 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
28710 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  i==0)..**.** SQL
28720 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
28730 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
28740 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75  .  So just becau
28750 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
28760 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
28770 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
28780 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
28790 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
287a0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
287b0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
287c0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
287d0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
287e0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
287f0 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
28800 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
28810 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a  t static.  Type.
28820 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
28830 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
28840 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
28850 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
28860 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
28870 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
28880 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
28890 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20  .**.** {H13761} 
288a0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
288b0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
288c0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53  olumn_decltype(S
288d0 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a  ,N)] returns a.*
288e0 2a 20 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  *           zero
288f0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
28900 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  8 string contain
28910 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64  ing the declared
28920 20 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 20 20   datatype.**    
28930 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 74 61         of the ta
28940 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
28950 61 70 70 65 61 72 73 20 61 73 20 74 68 65 20 4e  appears as the N
28960 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65  th column (numbe
28970 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
28980 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20   from 0) of the 
28990 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68  result set to th
289a0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
289b0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20  ement] S..**.** 
289c0 7b 48 31 33 37 36 32 7d 20 20 41 20 73 75 63 63  {H13762}  A succ
289d0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
289e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
289f0 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a  ecltype16(S,N)].
28a00 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
28a10 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  urns a zero-term
28a20 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61  inated UTF-16 na
28a30 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
28a40 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
28a50 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74      containing t
28a60 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61  he declared data
28a70 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
28a80 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70  e column that ap
28a90 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  pears.**        
28aa0 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f     as the Nth co
28ab0 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66  lumn (numbered f
28ac0 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65  rom 0) of the re
28ad0 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a  sult set to the.
28ae0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72  **           [pr
28af0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28b00 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ] S..**.** {H137
28b10 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73  63}  If N is les
28b20 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73  s than 0 or N is
28b30 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72   greater than or
28b40 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20   equal to.**    
28b50 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65         the numbe
28b60 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
28b70 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
28b80 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20  atement] S,.**  
28b90 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 74           or if t
28ba0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
28bb0 20 53 20 69 73 20 61 6e 20 65 78 70 72 65 73 73   S is an express
28bc0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20  ion or subquery 
28bd0 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  rather.**       
28be0 20 20 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65      than a table
28bf0 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61   column, or if a
28c00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
28c10 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20  on failure.**   
28c20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64          occurs d
28c30 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63  uring encoding c
28c40 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e  onversions, then
28c50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 61  .**           ca
28c60 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
28c70 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
28c80 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  S,N)] or.**     
28c90 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
28ca0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
28cb0 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55  (S,N)] return NU
28cc0 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  LL..*/.const cha
28cd0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
28ce0 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
28cf0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
28d00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
28d10 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
28d20 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
28d30 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
28d40 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
28d50 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
28d60 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31  ent {H13200} <S1
28d70 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  0000>.**.** Afte
28d80 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
28d90 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
28da0 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
28db0 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
28dc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
28dd0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
28de0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
28df0 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
28e00 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
28e10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28e20 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
28e30 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
28e40 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
28e50 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
28e60 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
28e70 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
28e80 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
28e90 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
28ea0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
28eb0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
28ec0 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
28ed0 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
28ee0 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
28ef0 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
28f00 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
28f10 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
28f20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28f30 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
28f40 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
28f50 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
28f60 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
28f70 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
28f80 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
28f90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
28fa0 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
28fb0 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
28fc0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
28fd0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
28fe0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
28ff0 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
29000 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
29010 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
29020 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  pported..**.** I
29030 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
29040 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
29050 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
29060 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
29070 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
29080 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
29090 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
290a0 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
290b0 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69  E_MISUSE]..** Wi
290c0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
290d0 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
290e0 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
290f0 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
29100 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
29110 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
29120 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
29130 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  **.** [SQLITE_BU
29140 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
29150 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
29160 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
29170 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
29180 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
29190 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
291a0 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73  s job.  If the s
291b0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
291c0 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
291d0 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
291e0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
291f0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
29200 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
29210 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
29220 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
29230 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
29240 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
29250 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74  in a.** explicit
29260 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
29270 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
29280 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
29290 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
292a0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
292b0 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20  * [SQLITE_DONE] 
292c0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
292d0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
292e0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
292f0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
29300 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
29310 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
29320 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
29330 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
29340 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
29350 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
29360 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
29370 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
29380 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
29390 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
293a0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
293b0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
293c0 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
293d0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
293e0 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
293f0 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
29400 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
29410 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
29420 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
29430 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
29440 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
29450 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
29460 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
29470 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
29480 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
29490 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
294a0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
294b0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
294c0 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
294d0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  .**.** [SQLITE_E
294e0 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
294f0 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
29500 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
29510 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
29520 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
29530 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
29540 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
29550 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
29560 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
29570 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
29580 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
29590 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
295a0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74  rrmsg()]..** Wit
295b0 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
295c0 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
295d0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
295e0 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
295f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
29600 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
29610 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
29620 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
29630 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
29640 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
29650 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
29660 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
29670 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
29680 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65  tement].  In the
29690 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
296a0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
296b0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
296c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
296d0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
296e0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
296f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
29700 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
29710 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
29720 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
29730 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
29740 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
29750 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
29760 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
29770 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
29780 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
29790 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
297a0 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
297b0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
297c0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
297d0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
297e0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
297f0 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
29800 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
29810 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
29820 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
29830 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
29840 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
29850 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
29860 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
29870 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
29880 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
29890 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
298a0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
298b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
298c0 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
298d0 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
298e0 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
298f0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
29900 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
29910 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
29920 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
29930 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
29940 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
29950 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
29960 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
29970 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
29980 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
29990 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
299a0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
299b0 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
299c0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
299d0 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
299e0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
299f0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
29a00 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
29a10 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
29a20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
29a30 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
29a40 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
29a50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
29a60 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
29a70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
29a80 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
29a90 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
29aa0 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
29ab0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
29ac0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
29ad0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
29ae0 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
29af0 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
29b00 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
29b10 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
29b20 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
29b30 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
29b40 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
29b50 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
29b60 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
29b70 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  mended..**.** IN
29b80 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
29b90 7b 48 31 33 32 30 32 7d 20 20 49 66 20 74 68 65  {H13202}  If the
29ba0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29bb0 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79  ment] S is ready
29bc0 20 74 6f 20 62 65 20 72 75 6e 2c 20 74 68 65 6e   to be run, then
29bd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
29be0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
29bf0 61 64 76 61 6e 63 65 73 20 74 68 61 74 20 70 72  advances that pr
29c00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29c10 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20   until.**       
29c20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f      completion o
29c30 72 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65  r until it is re
29c40 61 64 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e  ady to return an
29c50 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65  other row of the
29c60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
29c70 73 75 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e 74  sult set, or unt
29c80 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  il an [sqlite3_i
29c90 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
29ca0 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  rupt].**        
29cb0 20 20 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65     or a run-time
29cc0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
29cd0 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20 57  *.** {H15304}  W
29ce0 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  hen a call to [s
29cf0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
29d00 63 61 75 73 65 73 20 74 68 65 20 5b 70 72 65 70  causes the [prep
29d10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
29d20 2a 2a 20 20 20 20 20 20 20 20 20 20 20 53 20 74  **           S t
29d30 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  o run to complet
29d40 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74 69 6f  ion, the functio
29d50 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  n returns [SQLIT
29d60 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_DONE]..**.** {
29d70 48 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20  H15306}  When a 
29d80 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29d90 5f 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20  _step(S)] stops 
29da0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 72 65  because it is re
29db0 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ady to.**       
29dc0 20 20 20 20 72 65 74 75 72 6e 20 61 6e 6f 74 68      return anoth
29dd0 65 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  er row of the re
29de0 73 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74  sult set, it ret
29df0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57  urns [SQLITE_ROW
29e00 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38  ]..**.** {H15308
29e10 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20  }  If a call to 
29e20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
29e30 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a  ] encounters an.
29e40 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
29e50 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20  lite3_interrupt 
29e60 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20  | interrupt] or 
29e70 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
29e80 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69  ,.**           i
29e90 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  t returns an app
29ea0 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 63  ropriate error c
29eb0 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ode that is not 
29ec0 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  one of.**       
29ed0 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c      [SQLITE_OK],
29ee0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f   [SQLITE_ROW], o
29ef0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
29f00 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20  .**.** {H15310} 
29f10 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   If an [sqlite3_
29f20 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65  interrupt | inte
29f30 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d  rrupt] or a run-
29f40 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20  time error.**   
29f50 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64          occurs d
29f60 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  uring a call to 
29f70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
29f80 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66  ].**           f
29f90 6f 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  or a [prepared s
29fa0 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61  tatement] S crea
29fb0 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
29fc0 20 20 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e         legacy in
29fd0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
29fe0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a  3_prepare()] or.
29ff0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
2a000 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2a010 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e  )], then the fun
2a020 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69  ction returns ei
2a030 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
2a040 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d    [SQLITE_ERROR]
2a050 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
2a060 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
2a070 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  SE]..*/.int sqli
2a080 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
2a090 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2a0a0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2a0b0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2a0c0 20 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33   result set {H13
2a0d0 37 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  770} <S10700>.**
2a0e0 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20  .** Returns the 
2a0f0 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73  number of values
2a100 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2a110 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2a120 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  t set..**.** INV
2a130 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2a140 48 31 33 37 37 31 7d 20 20 41 66 74 65 72 20 61  H13771}  After a
2a150 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2a160 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74 20  3_step(S)] that 
2a170 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
2a180 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ROW],.**        
2a190 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
2a1a0 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72  data_count(S)] r
2a1b0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
2a1c0 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  rn the same valu
2a1d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  e.**           a
2a1e0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  s the [sqlite3_c
2a1f0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20  olumn_count(S)] 
2a200 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2a210 7b 48 31 33 37 37 32 7d 20 20 41 66 74 65 72 20  {H13772}  After 
2a220 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2a230 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61  ] has returned a
2a240 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
2a250 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  han.**          
2a260 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
2a270 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   before [sqlite3
2a280 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65  _step(S)] has be
2a290 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  en called on the
2a2a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70  .**           [p
2a2b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a2c0 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  t] for the first
2a2d0 20 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77   time since it w
2a2e0 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  as.**           
2a2f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a300 20 7c 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20   | prepared] or 
2a310 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c  [sqlite3_reset |
2a320 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20   reset],.**     
2a330 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
2a340 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29  e3_data_count(S)
2a350 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
2a360 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73  s zero..*/.int s
2a370 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2a380 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2a390 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2a3a0 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
2a3b0 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b  ntal Datatypes {
2a3c0 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e  H10265} <S10110>
2a3d0 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57  <S10120>.** KEYW
2a3e0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
2a3f0 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d  T.**.** {H10266}
2a400 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20   Every value in 
2a410 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
2a420 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
2a430 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
2a440 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2a450 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2a460 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
2a470 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
2a480 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2a490 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
2a4a0 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
2a4b0 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
2a4c0 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  l> {END}.**.** T
2a4d0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
2a4e0 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
2a4f0 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
2a500 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2a510 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
2a520 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
2a530 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
2a540 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
2a550 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
2a560 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
2a570 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
2a580 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
2a590 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
2a5a0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
2a5b0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
2a5c0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
2a5d0 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
2a5e0 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
2a5f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2a600 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
2a610 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
2a620 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2a630 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
2a640 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
2a650 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
2a660 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
2a670 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
2a680 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
2a690 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
2a6a0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
2a6b0 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
2a6c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a6d0 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
2a6e0 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31  From A Query {H1
2a6f0 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3800} <S10700>.*
2a700 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
2a710 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2a720 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
2a730 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
2a740 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20  the "result set 
2a750 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65  query" interface
2a760 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2a770 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
2a780 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2a790 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
2a7a0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
2a7b0 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
2a7c0 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65  a query.  In eve
2a7d0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
2a7e0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
2a7f0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
2a800 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2a810 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
2a820 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
2a830 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2a840 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
2a850 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
2a860 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2a870 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
2a880 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
2a890 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
2a8a0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2a8b0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
2a8c0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
2a8d0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
2a8e0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
2a8f0 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f   The leftmost co
2a900 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2a910 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
2a920 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66  ndex 0..**.** If
2a930 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2a940 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2a950 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2a960 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2a970 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2a980 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2a990 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2a9a0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2a9b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2a9c0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2a9d0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2a9e0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2a9f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2aa00 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2aa10 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2aa20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2aa30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2aa40 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2aa50 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2aa60 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2aa70 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2aa80 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2aa90 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2aaa0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2aab0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2aac0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2aad0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2aae0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2aaf0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2ab00 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2ab10 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2ab20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2ab30 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2ab40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ab50 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2ab60 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2ab70 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2ab80 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2ab90 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2aba0 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2abb0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2abc0 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2abd0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2abe0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2abf0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2ac00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2ac10 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2ac20 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2ac30 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
2ac40 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
2ac50 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
2ac60 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
2ac70 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65  ult column.  The
2ac80 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
2ac90 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2aca0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
2acb0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
2acc0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
2acd0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
2ace0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
2acf0 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
2ad00 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2ad10 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2ad20 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
2ad30 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
2ad40 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
2ad50 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
2ad60 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
2ad70 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
2ad80 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
2ad90 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
2ada0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2adb0 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
2adc0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
2add0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2ade0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
2adf0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
2ae00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2ae10 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
2ae20 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
2ae30 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  on..**.** If the
2ae40 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2ae50 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
2ae60 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2ae70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2ae80 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2ae90 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2aea0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2aeb0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2aec0 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
2aed0 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
2aee0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2aef0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2af00 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2af10 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2af20 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
2af30 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2af40 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68   bytes..** If th
2af50 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2af60 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2af70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2af80 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
2af90 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2afa0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2afb0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2afc0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
2afd0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2afe0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2aff0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2b000 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  ** The value ret
2b010 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
2b020 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2b030 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68  terminator at th
2b040 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
2b050 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61  string.  For cla
2b060 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20  rity: the value 
2b070 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20  returned is the 
2b080 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
2b090 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
2b0a0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2b0b0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
2b0c0 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65  **.** Strings re
2b0d0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2b0e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2b0f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2b100 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
2b110 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
2b120 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
2b130 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
2b140 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76   The return.** v
2b150 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
2b160 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2b170 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
2b180 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62  h BLOB is an arb
2b190 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65  itrary.** pointe
2b1a0 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e  r, possibly even
2b1b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2b1c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2b1d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2b1e0 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  6() routine is s
2b1f0 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65  imilar to sqlite
2b200 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2b210 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74  .** but leaves t
2b220 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46  he result in UTF
2b230 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79  -16 in native by
2b240 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64  te order instead
2b250 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68   of UTF-8..** Th
2b260 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
2b270 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  r is not include
2b280 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e  d in this count.
2b290 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63  .**.** The objec
2b2a0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
2b2b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2b2c0 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
2b2d0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2b2e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2b2f0 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
2b300 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2b310 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
2b320 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
2b330 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
2b340 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2b350 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2b360 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
2b370 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2b380 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2b390 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2b3a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2b3b0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2b3c0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
2b3d0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
2b3e0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
2b3f0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2b400 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
2b410 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2b420 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
2b430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2b440 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
2b450 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2b460 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
2b470 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
2b480 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
2b490 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
2b4a0 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f  appropriate.  Fo
2b4b0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
2b4c0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
2b4d0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
2b4e0 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
2b4f0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
2b500 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
2b510 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
2b520 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
2b530 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
2b540 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
2b550 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
2b560 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
2b570 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
2b580 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
2b590 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
2b5a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2b5b0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2b5c0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2b5d0 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
2b5e0 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
2b5f0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
2b600 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
2b610 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2b620 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
2b630 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
2b640 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
2b650 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2b660 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
2b670 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
2b680 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2b690 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2b6a0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
2b6b0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2b6c0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2b6d0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2b6e0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
2b6f0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2b700 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2b710 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2b720 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2b730 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
2b740 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
2b750 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
2b760 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2b770 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2b780 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
2b790 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2b7a0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2b7b0 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
2b7c0 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
2b7d0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2b7e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2b7f0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
2b800 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72  float to integer
2b810 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2b820 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
2b830 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2b840 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2b850 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2b860 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2b870 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2b880 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54  Same as FLOAT->T
2b890 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
2b8a0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
2b8b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65  TEGER   <td> Use
2b8c0 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
2b8d0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2b8e0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2b8f0 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   Use atof().** <
2b900 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2b910 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2b920 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
2b930 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2b940 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2b950 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2b960 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
2b970 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
2b980 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2b990 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2b9a0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
2b9b0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29   then use atof()
2b9c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2b9d0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
2b9e0 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
2b9f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2ba00 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
2ba10 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2ba20 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
2ba30 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
2ba40 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
2ba50 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
2ba60 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
2ba70 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
2ba80 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
2ba90 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
2baa0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
2bab0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
2bac0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
2bad0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
2bae0 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
2baf0 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
2bb00 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
2bb10 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
2bb20 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
2bb30 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
2bb40 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
2bb50 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
2bb60 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
2bb70 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
2bb80 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
2bb90 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
2bba0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
2bbb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2bbc0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
2bbd0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
2bbe0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
2bbf0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
2bc00 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
2bc10 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
2bc20 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
2bc30 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
2bc40 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
2bc50 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
2bc60 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
2bc70 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
2bc80 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2bc90 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
2bca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2bcb0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2bcc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2bcd0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2bce0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
2bcf0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
2bd00 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
2bd10 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
2bd20 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2bd30 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2bd40 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
2bd50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2bd60 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
2bd70 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2bd80 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2bd90 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2bda0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
2bdb0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
2bdc0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
2bdd0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
2bde0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2bdf0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
2be00 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2be10 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
2be20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2be30 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
2be40 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2be50 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2be60 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2be70 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
2be80 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72  ul>.**.** Conver
2be90 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
2bea0 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
2beb0 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
2bec0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
2bed0 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
2bee0 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
2bef0 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
2bf00 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
2bf10 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
2bf20 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
2bf30 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e  ior pointer poin
2bf40 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20  ts to will have 
2bf50 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
2bf60 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
2bf70 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
2bf80 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
2bf90 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
2bfa0 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
2bfb0 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
2bfc0 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
2bfd0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
2bfe0 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
2bff0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
2c000 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
2c010 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
2c020 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
2c030 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
2c040 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
2c050 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
2c060 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
2c070 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
2c080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c090 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
2c0a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c0b0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2c0c0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2c0d0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
2c0e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2c0f0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2c100 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2c110 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2c120 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2c130 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c140 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
2c150 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
2c160 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
2c170 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
2c180 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2c190 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
2c1a0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
2c1b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c1c0 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
2c1d0 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
2c1e0 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
2c1f0 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
2c200 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
2c210 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2c220 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2c230 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
2c240 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
2c250 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
2c260 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
2c270 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
2c280 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
2c290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c2a0 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
2c2b0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2c2c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
2c2d0 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
2c2e0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2c2f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2c300 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
2c310 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2c320 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
2c330 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
2c340 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
2c350 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
2c360 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
2c370 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
2c380 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
2c390 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c3a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2c3b0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2c3c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2c3d0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2c3e0 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
2c3f0 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
2c400 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
2c410 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
2c420 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
2c430 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
2c440 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
2c450 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2c460 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
2c470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c480 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
2c490 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
2c4a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  ()]..**.** If a 
2c4b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2c4c0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
2c4d0 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
2c4e0 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
2c4f0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2c500 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
2c510 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
2c520 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
2c530 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
2c540 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
2c550 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
2c560 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
2c570 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
2c580 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
2c590 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2c5a0 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
2c5b0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
2c5c0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
2c5d0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2c5e0 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54 68 65 20  ** {H13803} The 
2c5f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c600 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72  blob(S,N)] inter
2c610 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2c620 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
2c630 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2c640 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2c650 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
2c660 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
2c670 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2c680 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
2c690 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20 72 65  BLOB and then re
2c6a0 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20  turns a.**      
2c6b0 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74      pointer to t
2c6c0 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c  he converted val
2c6d0 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30  ue..**.** {H1380
2c6e0 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
2c6f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e  column_bytes(S,N
2c700 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2c710 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
2c720 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
2c730 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42  ytes in the BLOB
2c740 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c   or string (excl
2c750 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
2c760 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
2c770 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
2c780 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
2c790 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2c7a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
2c7b0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2c7c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c7d0 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a  _blob(S,N)] or.*
2c7e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2c7f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2c800 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  S,N)]..**.** {H1
2c810 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  3809} The [sqlit
2c820 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2c830 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
2c840 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2c850 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2c860 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2c870 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
2c880 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
2c890 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
2c8a0 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
2c8b0 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
2c8c0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2c8d0 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
2c8e0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2c8f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c900 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a  xt16(S,N)]..**.*
2c910 2a 20 7b 48 31 33 38 31 32 7d 20 54 68 65 20 5b  * {H13812} The [
2c920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2c930 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65  ouble(S,N)] inte
2c940 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2c950 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
2c960 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
2c970 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
2c980 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
2c990 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2c9a0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2c9b0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
2c9c0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2c9d0 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20  value and.**    
2c9e0 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
2c9f0 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c  copy of that val
2ca00 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31  ue..**.** {H1381
2ca10 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
2ca20 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d  column_int(S,N)]
2ca30 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2ca40 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2ca50 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
2ca60 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
2ca70 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2ca80 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  set for the.**  
2ca90 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2caa0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2cab0 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
2cac0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
2cad0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2cae0 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32  rns the lower 32
2caf0 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e   bits of that in
2cb00 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  teger..**.** {H1
2cb10 33 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  3818} The [sqlit
2cb20 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
2cb30 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2cb40 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2cb50 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
2cb60 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2cb70 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2cb80 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65  sult set for the
2cb90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2cba0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cbb0 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  ] S into a 64-bi
2cbc0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2cbd0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2cbe0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2cbf0 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
2cc00 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20  .**.** {H13821} 
2cc10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
2cc20 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69  umn_text(S,N)] i
2cc30 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2cc40 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2cc50 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
2cc60 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
2cc70 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2cc80 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
2cc90 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20    the [prepared 
2cca0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
2ccb0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2ccc0 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20  ted UTF-8.**    
2ccd0 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
2cce0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2ccf0 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2cd00 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34  g..**.** {H13824
2cd10 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2cd20 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e  olumn_text16(S,N
2cd30 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2cd40 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2cd50 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
2cd60 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2cd70 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2cd80 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a  t set for the.**
2cd90 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
2cda0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2cdb0 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
2cdc0 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
2cdd0 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
2cde0 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  ed UTF-16 native
2cdf0 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69   byte order stri
2ce00 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2ce10 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69  *          a poi
2ce20 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
2ce30 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  ing..**.** {H138
2ce40 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  27} The [sqlite3
2ce50 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e  _column_type(S,N
2ce60 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2ce70 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
2ce80 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2ce90 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  NULL], [SQLITE_I
2cea0 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
2ceb0 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20  _FLOAT],.**     
2cec0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58       [SQLITE_TEX
2ced0 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42  T], or [SQLITE_B
2cee0 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
2cef0 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ate for.**      
2cf00 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75      the Nth colu
2cf10 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
2cf20 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2cf30 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
2cf40 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
2cf50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cf60 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33   S..**.** {H1383
2cf70 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  0} The [sqlite3_
2cf80 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e  column_value(S,N
2cf90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2cfa0 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
2cfb0 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e     pointer to an
2cfc0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2cfd0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2cfe0 65 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  ect for the.**  
2cff0 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
2d000 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
2d010 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2d020 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
2d030 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
2d040 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d050 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69   S..*/.const voi
2d060 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2d070 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
2d080 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d090 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2d0a0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
2d0b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d0c0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2d0d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
2d0e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d0f0 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
2d100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2d110 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2d120 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2d130 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2d140 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
2d150 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d160 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
2d170 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2d180 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2d190 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
2d1a0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2d1b0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2d1c0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
2d1d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d1e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2d1f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2d200 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2d210 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2d220 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d230 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
2d240 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
2d250 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
2d260 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2d270 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2d280 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
2d290 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2d2a0 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
2d2b0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
2d2c0 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 30 33  t {H13300} <S703
2d2d0 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a  00><S30100>.**.*
2d2e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69  * The sqlite3_fi
2d2f0 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
2d300 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
2d310 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
2d320 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2d330 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2d340 74 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73  t was executed s
2d350 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e  uccessfully or n
2d360 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61  ot executed at a
2d370 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49  ll, then.** SQLI
2d380 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65  TE_OK is returne
2d390 64 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20  d. If execution 
2d3a0 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
2d3b0 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a   failed then an.
2d3c0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
2d3d0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
2d3e0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
2d3f0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rned..**.** This
2d400 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2d410 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
2d420 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65  int during the e
2d430 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a  xecution of the.
2d440 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2d450 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65  tement].  If the
2d460 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
2d470 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70   has not.** comp
2d480 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20  leted execution 
2d490 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  when this routin
2d4a0 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61  e is called, tha
2d4b0 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63  t is like.** enc
2d4c0 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72  ountering an err
2d4d0 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  or or an [sqlite
2d4e0 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e  3_interrupt | in
2d4f0 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63  terrupt]..** Inc
2d500 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20  omplete updates 
2d510 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  may be rolled ba
2d520 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69  ck and transacti
2d530 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a  ons canceled,.**
2d540 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
2d550 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
2d560 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72   and the.** [err
2d570 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65  or code] returne
2d580 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54  d will be [SQLIT
2d590 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
2d5a0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2d5b0 2a 20 7b 48 31 31 33 30 32 7d 20 54 68 65 20 5b  * {H11302} The [
2d5c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2d5d0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
2d5e0 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20  estroys the.**  
2d5f0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2d600 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61  d statement] S a
2d610 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a  nd releases all.
2d620 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f  **          memo
2d630 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f  ry and file reso
2d640 75 72 63 65 73 20 68 65 6c 64 20 62 79 20 74 68  urces held by th
2d650 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  at object..**.**
2d660 20 7b 48 31 31 33 30 34 7d 20 49 66 20 74 68 65   {H11304} If the
2d670 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2d680 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2d690 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
2d6a0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2d6b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d6c0 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72  S returned an er
2d6d0 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ror,.**         
2d6e0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   then [sqlite3_f
2d6f0 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75  inalize(S)] retu
2d700 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65 72  rns that same er
2d710 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ror..*/.int sqli
2d720 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
2d730 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2d740 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d750 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
2d760 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2d770 62 6a 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c  bject {H13330} <
2d780 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S70300>.**.** Th
2d790 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
2d7a0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
2d7b0 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
2d7c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d7d0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
2d7e0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
2d7f0 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
2d800 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
2d810 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74  d..** Any SQL st
2d820 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
2d830 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
2d840 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
2d850 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
2d860 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2d870 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
2d880 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
2d890 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
2d8a0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
2d8b0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
2d8c0 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
2d8d0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  ings..**.** {H11
2d8e0 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  332} The [sqlite
2d8f0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2d900 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
2d910 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d920 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20  ment] S.**      
2d930 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20      back to the 
2d940 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
2d950 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
2d960 7b 48 31 31 33 33 34 7d 20 49 66 20 74 68 65 20  {H11334} If the 
2d970 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2d980 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2d990 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2d9a0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
2d9b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2d9c0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2d9d0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
2d9e0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20  E_DONE],.**     
2d9f0 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69       or if [sqli
2da00 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
2da10 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
2da20 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
2da30 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
2da40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2da50 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
2da60 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ITE_OK]..**.** {
2da70 48 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d  H11336} If the m
2da80 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2da90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2daa0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2dab0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2dac0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2dad0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
2dae0 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  or, then.**     
2daf0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
2db00 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
2db10 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
2db20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
2db30 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20  ** {H11338} The 
2db40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2db50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
2db60 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2db70 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20   values.**      
2db80 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69      of any [sqli
2db90 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
2dba0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
2dbb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2dbc0 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nt] S..*/.int sq
2dbd0 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69  lite3_reset(sqli
2dbe0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2dbf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2dc00 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64  F: Create Or Red
2dc10 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69  efine SQL Functi
2dc20 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32  ons {H16100} <S2
2dc30 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
2dc40 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
2dc50 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
2dc60 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2dc70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2dc80 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
2dc90 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
2dca0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2dcb0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
2dcc0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f  .**.** These two
2dcd0 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
2dce0 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
2dcf0 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
2dd00 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
2dd10 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
2dd20 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
2dd30 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
2dd40 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
2dd50 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
2dd60 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
2dd70 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
2dd80 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
2dd90 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77   difference betw
2dda0 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69  een the.** two i
2ddb0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
2ddc0 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  d parameter, the
2ddd0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63   name of the (sc
2dde0 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f  alar) function o
2ddf0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20  r.** aggregate, 
2de00 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  is encoded in UT
2de10 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  F-8 for sqlite3_
2de20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2de30 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20  ) and UTF-16.** 
2de40 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
2de50 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e  te_function16().
2de60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
2de70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2de80 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2de90 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
2dea0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
2deb0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
2dec0 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c  ded.  If a singl
2ded0 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d  e program uses m
2dee0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
2def0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2df00 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20  ion internally, 
2df10 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  then SQL functio
2df20 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
2df30 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f   individually to
2df40 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61 73  .** each databas
2df50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a  e connection..**
2df60 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
2df70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2df80 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
2df90 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
2dfa0 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
2dfb0 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e  efined.  The len
2dfc0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
2dfd0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
2dfe0 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69  5 bytes, exclusi
2dff0 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72  ve of.** the zer
2e000 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e  o-terminator.  N
2e010 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
2e020 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  e length limit i
2e030 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a  s in bytes, not.
2e040 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20  ** characters.  
2e050 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
2e060 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
2e070 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
2e080 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
2e090 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52  lt in [SQLITE_ER
2e0a0 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72  ROR] being retur
2e0b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ned..**.** The t
2e0c0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
2e0d0 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
2e0e0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2e0f0 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
2e100 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2e110 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
2e120 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   If this paramet
2e130 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
2e140 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
2e150 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2e160 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
2e170 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2e180 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  uments..**.** Th
2e190 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2e1a0 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
2e1b0 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
2e1c0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
2e1d0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
2e1e0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
2e1f0 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
2e200 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
2e210 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  Any SQL function
2e220 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e230 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74  should be able t
2e240 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77  o work.** work w
2e250 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
2e260 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
2e270 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
2e280 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
2e290 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
2e2a0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
2e2b0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
2e2c0 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f  her.  It is allo
2e2d0 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  wed to.** invoke
2e2e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2e2f0 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
2e300 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2e310 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
2e320 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
2e330 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2e340 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
2e350 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
2e360 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65  eTextRep..** Whe
2e370 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
2e380 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2e390 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2e3a0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
2e3b0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
2e3c0 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
2e3d0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
2e3e0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
2e3f0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
2e400 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
2e410 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
2e420 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
2e430 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
2e440 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
2e450 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
2e460 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
2e470 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
2e480 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
2e490 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61  .** The fifth pa
2e4a0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
2e4b0 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
2e4c0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
2e4d0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
2e4e0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
2e4f0 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
2e500 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
2e510 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2e520 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ()]..**.** The s
2e530 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61  eventh, eighth a
2e540 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  nd ninth paramet
2e550 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
2e560 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
2e570 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
2e580 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
2e590 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
2e5a0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
2e5b0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2e5c0 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20  egate. A scalar 
2e5d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2e5e0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2e5f0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
2e600 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
2e610 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e   only, NULL poin
2e620 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70  ters should be p
2e630 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
2e640 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
2e650 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20   parameters. An 
2e660 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2e670 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2e680 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2e690 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
2e6a0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
2e6b0 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  L should be pass
2e6c0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f  ed for xFunc. To
2e6d0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
2e6e0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
2e6f0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2e700 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20  , pass NULL for 
2e710 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
2e720 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  on callbacks..**
2e730 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74  .** It is permit
2e740 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
2e750 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2e760 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2e770 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
2e780 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2e790 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
2e7a0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
2e7b0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
2e7c0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
2e7d0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
2e7e0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53  xt encodings.  S
2e7f0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
2e800 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
2e810 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  tion most closel
2e820 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
2e830 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
2e840 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
2e850 73 20 75 73 65 64 2e 20 20 41 20 66 75 6e 63 74  s used.  A funct
2e860 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2e870 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
2e880 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
2e890 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
2e8a0 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
2e8b0 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
2e8c0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
2e8d0 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
2e8e0 67 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 77  g.  A function w
2e8f0 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
2e900 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2e910 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
2e920 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
2e930 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
2e940 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
2e950 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2e960 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2e970 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66  ferent.  .** A f
2e980 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2e990 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2e9a0 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
2e9b0 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
2e9c0 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
2e9d0 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
2e9e0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2e9f0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
2ea00 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
2ea10 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
2ea20 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c  TF16..**.** Buil
2ea30 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
2ea40 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
2ea50 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
2ea60 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2ea70 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69  tions..** The fi
2ea80 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  rst application-
2ea90 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2eaa0 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61   with a given na
2eab0 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c  me overrides all
2eac0 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e  .** built-in fun
2ead0 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61  ctions in the sa
2eae0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
2eaf0 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68  nection] with th
2eb00 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20  e same name..** 
2eb10 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69  Subsequent appli
2eb20 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2eb30 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  unctions of the 
2eb40 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f  same name only o
2eb50 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f  verride .** prio
2eb60 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  r application-de
2eb70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20  fined functions 
2eb80 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 61 63  that are an exac
2eb90 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a  t match for the.
2eba0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72  ** number of par
2ebb0 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65 66  ameters and pref
2ebc0 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a  erred encoding..
2ebd0 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61  **.** An applica
2ebe0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2ebf0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
2ec00 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
2ec10 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
2ec20 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
2ec30 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
2ec40 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
2ec50 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2ec60 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
2ec70 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
2ec80 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2ec90 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
2eca0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
2ecb0 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e  unning..**.** IN
2ecc0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2ecd0 7b 48 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71  {H16103} The [sq
2ece0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ecf0 63 74 69 6f 6e 31 36 28 44 2c 58 2c 2e 2e 2e 29  ction16(D,X,...)
2ed00 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c  ] interface shal
2ed10 6c 20 62 65 68 61 76 65 0a 2a 2a 20 20 20 20 20  l behave.**     
2ed20 20 20 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33       as [sqlite3
2ed30 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ed40 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 20 65 76  (D,X,...)] in ev
2ed50 65 72 79 20 77 61 79 20 65 78 63 65 70 74 20 74  ery way except t
2ed60 68 61 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20  hat it.**       
2ed70 20 20 20 69 6e 74 65 72 70 72 65 74 73 20 74 68     interprets th
2ed80 65 20 58 20 61 72 67 75 6d 65 6e 74 20 61 73 20  e X argument as 
2ed90 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2eda0 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20  UTF-16.**       
2edb0 20 20 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f     native byte o
2edc0 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  rder instead of 
2edd0 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  as zero-terminat
2ede0 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  ed UTF-8..**.** 
2edf0 7b 48 31 36 31 30 36 7d 20 41 20 73 75 63 63 65  {H16106} A succe
2ee00 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
2ee10 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2ee20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
2ee30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2ee40 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  ,N,E,...)] inter
2ee50 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73  face shall regis
2ee60 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
2ee70 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c  or replaces call
2ee80 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69  back functions i
2ee90 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
2eea0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
2eeb0 20 20 20 20 20 20 20 20 20 20 75 73 65 64 20 74            used t
2eec0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  o implement the 
2eed0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d  SQL function nam
2eee0 65 64 20 58 20 77 69 74 68 20 4e 20 70 61 72 61  ed X with N para
2eef0 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  meters.**       
2ef00 20 20 20 61 6e 64 20 68 61 76 69 6e 67 20 61 20     and having a 
2ef10 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
2ef20 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a  ncoding of E..**
2ef30 0a 2a 2a 20 7b 48 31 36 31 30 39 7d 20 41 20 73  .** {H16109} A s
2ef40 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
2ef50 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2ef60 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2ef70 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20  ,E,P,F,S,L)].** 
2ef80 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72           shall r
2ef90 65 70 6c 61 63 65 20 74 68 65 20 50 2c 20 46 2c  eplace the P, F,
2efa0 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73   S, and L values
2efb0 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20   from any prior 
2efc0 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20  calls with.**   
2efd0 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
2efe0 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76  D, X, N, and E v
2eff0 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  alues..**.** {H1
2f000 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6112} The [sqlit
2f010 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f020 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74  on(D,X,...)] int
2f030 65 72 66 61 63 65 20 73 68 61 6c 6c 20 66 61 69  erface shall fai
2f040 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66  l.**          if
2f050 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2f060 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20  n name X is.**  
2f070 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74          longer t
2f080 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65 78  han 255 bytes ex
2f090 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
2f0a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
2f0b0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20 54  **.** {H16118} T
2f0c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2f0d0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2f0e0 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 69 6e  N,E,P,F,S,L)] in
2f0f0 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20  terface.**      
2f100 20 20 20 20 73 68 61 6c 6c 20 66 61 69 6c 20 75      shall fail u
2f110 6e 6c 65 73 73 20 65 69 74 68 65 72 20 46 20 69  nless either F i
2f120 73 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64  s NULL and S and
2f130 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20   L are non-NULL 
2f140 6f 72 0a 2a 2a 2a 20 20 20 20 20 20 20 20 20 46  or.***         F
2f150 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64   is non-NULL and
2f160 20 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c   S and L are NUL
2f170 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 31  L..**.** {H16121
2f180 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2f190 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2f1a0 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
2f1b0 20 73 68 61 6c 6c 20 66 61 69 6c 73 20 77 69 74   shall fails wit
2f1c0 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  h an.**         
2f1d0 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b   error code of [
2f1e0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20  SQLITE_BUSY] if 
2f1f0 74 68 65 72 65 20 65 78 69 73 74 20 5b 70 72 65  there exist [pre
2f200 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2f210 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  ].**          as
2f220 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
2f230 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2f240 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
2f250 20 7b 48 31 36 31 32 34 7d 20 54 68 65 20 5b 73   {H16124} The [s
2f260 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f270 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e  nction(D,X,N,...
2f280 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
2f290 6c 6c 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20  ll fail with.** 
2f2a0 20 20 20 20 20 20 20 20 20 61 6e 20 65 72 72 6f           an erro
2f2b0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
2f2c0 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61 72 61  E_ERROR] if para
2f2d0 6d 65 74 65 72 20 4e 20 69 73 20 6c 65 73 73 0a  meter N is less.
2f2e0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e  **          than
2f2f0 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
2f300 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b  han 127..**.** {
2f310 48 31 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69  H16127} When N i
2f320 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
2f330 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2f340 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2f350 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
2f360 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 73       interface s
2f370 68 61 6c 6c 20 72 65 67 69 73 74 65 72 20 63 61  hall register ca
2f380 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e  llbacks to be in
2f390 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  voked for the.**
2f3a0 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 66 75            SQL fu
2f3b0 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
2f3c0 20 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20     named X when 
2f3d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
2f3e0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53  guments to the S
2f3f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a  QL function is.*
2f400 2a 20 20 20 20 20 20 20 20 20 20 65 78 61 63 74  *          exact
2f410 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ly N..**.** {H16
2f420 31 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d  130} When N is -
2f430 31 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  1, the [sqlite3_
2f440 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2f450 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  D,X,N,...)].**  
2f460 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
2f470 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74 65 72  e shall register
2f480 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65   callbacks to be
2f490 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65   invoked for the
2f4a0 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20   SQL.**         
2f4b0 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20   function named 
2f4c0 58 20 77 69 74 68 20 61 6e 79 20 6e 75 6d 62 65  X with any numbe
2f4d0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a  r of arguments..
2f4e0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 33 7d 20 57  **.** {H16133} W
2f4f0 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  hen calls to [sq
2f500 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f510 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29  ction(D,X,N,...)
2f520 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70  ].**          sp
2f530 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69  ecify multiple i
2f540 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2f550 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2f560 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20  ion X.**        
2f570 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69    and when one i
2f580 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61  mplementation ha
2f590 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f  s N>=0 and the o
2f5a0 74 68 65 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a  ther has N=(-1).
2f5b0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2f5c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2f5d0 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e  ith a non-zero N
2f5e0 20 73 68 61 6c 6c 20 62 65 20 70 72 65 66 65 72   shall be prefer
2f5f0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  red..**.** {H161
2f600 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74  36} When calls t
2f610 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
2f620 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2f630 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,E,...)].**     
2f640 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c       specify mul
2f650 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2f660 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2f670 65 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74  e function X wit
2f680 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  h.**          th
2f690 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66  e same number of
2f6a0 20 61 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 74   arguments N but
2f6b0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 0a   with different.
2f6c0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f  **          enco
2f6d0 64 69 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 68  dings E, then th
2f6e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f6f0 20 77 68 65 72 65 20 45 20 6d 61 74 63 68 65 73   where E matches
2f700 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2f710 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
2f720 6e 67 20 73 68 61 6c 6c 20 70 72 65 66 65 72 72  ng shall preferr
2f730 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33  ed..**.** {H1613
2f740 39 7d 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67  9} For an aggreg
2f750 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2f760 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
2f770 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2f780 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f790 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c  ion(D,X,N,E,P,0,
2f7a0 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c 69  S,L)] the finali
2f7b0 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zer.**          
2f7c0 66 75 6e 63 74 69 6f 6e 20 4c 20 73 68 61 6c 6c  function L shall
2f7d0 20 61 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b   always be invok
2f7e0 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20  ed exactly once 
2f7f0 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  if the.**       
2f800 20 20 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e     step function
2f810 20 53 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65   S is called one
2f820 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
2f830 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34 32 7d 20 57  **.** {H16142} W
2f840 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
2f850 65 73 20 65 69 74 68 65 72 20 74 68 65 20 78 46  es either the xF
2f860 75 6e 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e  unc or xStep fun
2f870 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20  ction of.**     
2f880 20 20 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74       an applicat
2f890 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2f8a0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
2f8b0 65 67 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a  egate created.**
2f8c0 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71            by [sq
2f8d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f8e0 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c  ction()] or [sql
2f8f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f900 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  tion16()],.**   
2f910 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
2f920 61 72 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65  array of [sqlite
2f930 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
2f940 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a   passed as the.*
2f950 2a 20 20 20 20 20 20 20 20 20 20 74 68 69 72 64  *          third
2f960 20 70 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c   parameter shall
2f970 20 62 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73   be [protected s
2f980 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2f990 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  jects..*/.int sq
2f9a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f9b0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
2f9c0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2f9d0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2f9e0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2f9f0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2fa00 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2fa10 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2fa20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2fa30 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2fa40 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2fa50 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2fa60 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2fa70 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2fa80 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2fa90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
2faa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2fab0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
2fac0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2fad0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
2fae0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2faf0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2fb00 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2fb10 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2fb20 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2fb30 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2fb40 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2fb50 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2fb60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2fb70 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2fb80 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2fb90 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2fba0 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  text*).);../*.**
2fbb0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
2fbc0 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36  Encodings {H1026
2fbd0 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36  7} <S50200> <H16
2fbe0 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  100>.**.** These
2fbf0 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
2fc00 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
2fc10 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
2fc20 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
2fc30 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
2fc40 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
2fc50 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2fc60 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
2fc70 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2fc80 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20  TE_UTF16LE      
2fc90 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2fca0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
2fcb0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
2fcc0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
2fcd0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
2fce0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
2fcf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2fd00 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
2fd10 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   5    /* sqlite3
2fd20 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2fd30 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
2fd40 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
2fd50 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
2fd60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2fd70 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
2fd80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2fd90 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
2fda0 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
2fdb0 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
2fdc0 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
2fdd0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
2fde0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
2fdf0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
2fe00 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
2fe10 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
2fe20 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
2fe30 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
2fe40 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
2fe50 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
2fe60 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
2fe70 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
2fe80 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
2fe90 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
2fea0 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
2feb0 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
2fec0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
2fed0 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
2fee0 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
2fef0 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
2ff00 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
2ff10 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
2ff20 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2ff30 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
2ff40 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
2ff50 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
2ff60 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2ff70 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
2ff80 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(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 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
2ffc0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
2ffd0 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
2ffe0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2fff0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
30000 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
30010 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
30020 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
30030 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
30040 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
30050 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
30060 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
30070 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
30080 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
30090 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
300a0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
300b0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
300c0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
300d0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
300e0 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48  ameter Values {H
300f0 31 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  15100} <S20200>.
30100 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
30110 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
30120 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
30130 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
30140 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
30150 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
30160 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
30170 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
30180 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
30190 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
301a0 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
301b0 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
301c0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
301d0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
301e0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
301f0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
30200 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30210 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
30220 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30230 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
30240 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
30250 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
30260 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
30270 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
30280 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
30290 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
302a0 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
302b0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
302c0 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
302d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
302e0 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
302f0 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
30300 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
30310 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
30320 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
30330 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
30340 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
30350 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
30360 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
30370 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
30380 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
30390 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
303a0 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
303b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
303c0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
303d0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
303e0 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
303f0 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
30400 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30410 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
30420 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
30430 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
30440 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
30450 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
30460 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
30470 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
30480 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
30490 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20  ** except that  
304a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
304b0 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
304c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
304d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
304e0 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
304f0 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
30500 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
30510 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
30520 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
30530 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
30540 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
30550 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
30560 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
30570 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
30580 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
30590 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
305a0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
305b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
305c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
305d0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
305e0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
305f0 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
30600 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
30610 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
30620 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
30630 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
30640 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
30650 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
30660 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
30670 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
30680 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
30690 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
306a0 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
306b0 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
306c0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
306d0 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
306e0 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
306f0 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
30700 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
30710 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
30720 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
30730 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
30740 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
30750 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
30760 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
30770 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
30780 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
30790 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
307a0 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
307b0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
307c0 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
307d0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
307e0 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
307f0 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
30800 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  d..**.** Please 
30810 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
30820 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
30830 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
30840 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
30850 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
30860 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
30870 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30880 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
30890 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
308a0 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
308b0 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
308c0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
308d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
308e0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
308f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
30900 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
30910 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
30920 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
30930 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
30940 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
30950 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
30960 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
30970 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
30980 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
30990 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
309a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
309b0 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
309c0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
309d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 33 7d 20  .**.** {H15103} 
309e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
309f0 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65  ue_blob(V)] inte
30a00 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
30a10 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
30a20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30a30 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
30a40 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e  V into a BLOB an
30a50 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  d then.**       
30a60 20 20 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69     returns a poi
30a70 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76  nter to the conv
30a80 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a  erted value..**.
30a90 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54 68 65 20  ** {H15106} The 
30aa0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
30ab0 79 74 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61  ytes(V)] interfa
30ac0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ce returns the.*
30ad0 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
30ae0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
30af0 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
30b00 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74   (exclusive of t
30b10 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  he.**          z
30b20 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f  ero terminator o
30b30 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68  n the string) th
30b40 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
30b50 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
30b60 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63     most recent c
30b70 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
30b80 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f  value_blob(V)] o
30b90 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
30ba0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30bb0 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  t(V)]..**.** {H1
30bc0 35 31 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  5109} The [sqlit
30bd0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
30be0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (V)] interface r
30bf0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
30c00 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
30c10 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
30c20 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20  ring (exclusive 
30c30 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
30c40 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74     zero terminat
30c50 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
30c60 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
30c70 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ned by the.**   
30c80 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65         most rece
30c90 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
30ca0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
30cb0 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  (V)],.**        
30cc0 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65    [sqlite3_value
30cd0 5f 74 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f  _text16be(V)], o
30ce0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
30cf0 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a  _text16le(V)]..*
30d00 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d 20 54 68  *.** {H15112} Th
30d10 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
30d20 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65  _double(V)] inte
30d30 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
30d40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
30d50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30d60 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
30d70 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e  V into a floatin
30d80 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e  g point value an
30d90 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
30da0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
30db0 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  that value..**.*
30dc0 2a 20 7b 48 31 35 31 31 35 7d 20 54 68 65 20 5b  * {H15115} The [
30dd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
30de0 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(V)] interface 
30df0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
30e00 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
30e10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30e20 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
30e30 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
30e40 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20   integer and.** 
30e50 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
30e60 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69   the lower 32 bi
30e70 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  ts of that integ
30e80 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31  er..**.** {H1511
30e90 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
30ea0 76 61 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20  value_int64(V)] 
30eb0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
30ec0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
30ed0 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
30ee0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
30ef0 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d  ect V into a 64-
30f00 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
30f10 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  er and.**       
30f20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
30f30 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65  y of that intege
30f40 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 31  r..**.** {H15121
30f50 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
30f60 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e  alue_text(V)] in
30f70 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
30f80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30f90 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
30fa0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30fb0 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  t V into a zero-
30fc0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
30fd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
30fe0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ing and returns 
30ff0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
31000 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
31010 7b 48 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71  {H15124} The [sq
31020 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31030 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  16(V)] interface
31040 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
31050 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
31060 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
31070 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
31080 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
31090 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
310a0 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
310b0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
310c0 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
310d0 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
310e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
310f0 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
31100 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 37 7d 20  .**.** {H15127} 
31110 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
31120 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20  ue_text16be(V)] 
31130 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
31140 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
31150 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
31160 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31170 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72  ect V into a zer
31180 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62  o-terminated 2-b
31190 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  yte.**          
311a0 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62  aligned UTF-16 b
311b0 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  ig-endian.**    
311c0 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
311d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
311e0 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
311f0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 30  g..**.** {H15130
31200 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
31210 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29  alue_text16le(V)
31220 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
31230 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
31240 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
31250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31260 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
31270 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32  ero-terminated 2
31280 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  -byte.**        
31290 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36    aligned UTF-16
312a0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a   little-endian.*
312b0 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
312c0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
312d0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
312e0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
312f0 31 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69  15133} The [sqli
31300 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56  te3_value_type(V
31310 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
31320 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
31330 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
31340 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  NULL], [SQLITE_I
31350 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
31360 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20  _FLOAT],.**     
31370 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58       [SQLITE_TEX
31380 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42  T], or [SQLITE_B
31390 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
313a0 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ate for.**      
313b0 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
313c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
313d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 36 7d  ..**.** {H15136}
313e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
313f0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
31400 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
31410 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20  onverts.**      
31420 20 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74      the [protect
31430 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31440 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
31450 65 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65  either an intege
31460 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  r or.**         
31470 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
31480 74 20 76 61 6c 75 65 20 69 66 20 69 74 20 63 61  t value if it ca
31490 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20  n do so without 
314a0 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  loss of.**      
314b0 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c      information,
314c0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65   and returns one
314d0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   of [SQLITE_NULL
314e0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
314f0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
31500 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
31510 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
31520 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
31530 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
31540 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
31550 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
31560 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
31570 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
31580 20 56 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e   V after the con
31590 76 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e  version attempt.
315a0 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
315b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
315c0 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
315d0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
315e0 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
315f0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
31600 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
31610 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
31620 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73  alue*);.double s
31630 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
31640 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
31650 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
31660 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
31670 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69  e3_value*);.sqli
31680 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
31690 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
316a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
316b0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
316c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
316d0 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
316e0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
316f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
31700 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
31710 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
31720 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
31730 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
31740 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
31750 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
31760 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
31770 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31780 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
31790 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
317a0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
317b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
317c0 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
317d0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
317e0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
317f0 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
31800 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31  tion Context {H1
31810 36 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6210} <S20200>.*
31820 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65  *.** The impleme
31830 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65  ntation of aggre
31840 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
31850 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74  ns use this rout
31860 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a  ine to allocate.
31870 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66  ** a structure f
31880 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
31890 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   state..**.** Th
318a0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
318b0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
318c0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75  te_context() rou
318d0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66  tine is called f
318e0 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c  or a.** particul
318f0 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51  ar aggregate, SQ
31900 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e  Lite allocates n
31910 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c  Bytes of memory,
31920 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
31930 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  .** memory, and 
31940 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
31950 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f  r to it. On seco
31960 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
31970 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
31980 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31990 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
319a0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
319b0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c   function index,
319c0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
319d0 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
319e0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
319f0 69 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65  ion of the aggre
31a00 67 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20  gate can use.** 
31a10 74 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66  the returned buf
31a20 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74  fer to accumulat
31a30 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51  e data..**.** SQ
31a40 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
31a50 6c 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c  ly frees the all
31a60 6f 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68  ocated buffer wh
31a70 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
31a80 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  .** query conclu
31a90 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
31aa0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73  irst parameter s
31ab0 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20  hould be a copy 
31ac0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
31ad0 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
31ae0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
31af0 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
31b00 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
31b10 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
31b20 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
31b30 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
31b40 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
31b50 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
31b60 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
31b70 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
31b80 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
31b90 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
31ba0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
31bb0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
31bc0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
31bd0 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20 54 68 65  .** {H16211} The
31be0 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f   first invocatio
31bf0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67  n of [sqlite3_ag
31c00 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31c10 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20  C,N)] for.**    
31c20 20 20 20 20 20 20 61 20 70 61 72 74 69 63 75 6c        a particul
31c30 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61  ar instance of a
31c40 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  n aggregate func
31c50 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74  tion (for a part
31c60 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20  icular.**       
31c70 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61     context C) ca
31c80 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61  uses SQLite to a
31c90 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74 65 73 20  llocate N bytes 
31ca0 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20  of memory,.**   
31cb0 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61 74         zero that
31cc0 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
31cd0 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  urn a pointer to
31ce0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 6d   the allocated m
31cf0 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  emory..**.** {H1
31d00 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72  6213} If a memor
31d10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
31d20 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
31d30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
31d40 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31d50 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 68  context(C,N)] th
31d60 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
31d70 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a  returns 0..**.**
31d80 20 7b 48 31 36 32 31 35 7d 20 53 65 63 6f 6e 64   {H16215} Second
31d90 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
31da0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a  invocations of.*
31db0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
31dc0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
31dd0 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20  ntext(C,N)] for 
31de0 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78 74  the same context
31df0 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20   pointer C.**   
31e00 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74 68         ignore th
31e10 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61 6e  e N parameter an
31e20 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74  d return a point
31e30 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a  er to the same.*
31e40 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63 6b  *          block
31e50 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 72   of memory retur
31e60 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ned by the first
31e70 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
31e80 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54 68 65 20  ** {H16217} The 
31e90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
31ea0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67 67   by [sqlite3_agg
31eb0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
31ec0 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20  ,N)] is.**      
31ed0 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c      automaticall
31ee0 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20 6e  y freed on the n
31ef0 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ext call to [sql
31f00 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
31f10 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
31f20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
31f30 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  ] for the [prepa
31f40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 63  red statement] c
31f50 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20  ontaining.**    
31f60 20 20 20 20 20 20 74 68 65 20 61 67 67 72 65 67        the aggreg
31f70 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 73  ate function ass
31f80 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f 6e  ociated with con
31f90 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20  text C..*/.void 
31fa0 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
31fb0 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
31fc0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
31fd0 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
31fe0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
31ff0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
32000 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c 53 32 30  ns {H16240} <S20
32010 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  200>.**.** The s
32020 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
32030 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
32040 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
32050 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
32060 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
32070 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
32080 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
32090 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
320a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
320b0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
320c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
320d0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
320e0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
320f0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
32100 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
32110 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
32120 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ction. {END}.**.
32130 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
32140 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
32150 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
32160 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
32170 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
32180 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32190 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
321a0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
321b0 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d 20 54 68  *.** {H16243} Th
321c0 65 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  e [sqlite3_user_
321d0 64 61 74 61 28 43 29 5d 20 69 6e 74 65 72 66 61  data(C)] interfa
321e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
321f0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  y of the.**     
32200 20 20 20 20 20 50 20 70 6f 69 6e 74 65 72 20 66       P pointer f
32210 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
32220 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32230 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
32240 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
32250 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
32260 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58  e_function16(D,X
32270 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63  ,N,E,P,F,S,L)] c
32280 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20  all that.**     
32290 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
322a0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
322b0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
322c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
322d0 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  t] C..*/.void *s
322e0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
322f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32300 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
32310 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
32320 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
32330 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20  ctions {H16250} 
32340 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e  <S60600><S20200>
32350 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
32360 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
32370 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
32380 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
32390 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
323a0 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
323b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
323c0 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
323d0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
323e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
323f0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
32400 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32410 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
32420 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
32430 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
32440 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
32450 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
32460 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ction..**.** INV
32470 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
32480 48 31 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c  H16253} The [sql
32490 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
324a0 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72  handle(C)] inter
324b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
324c0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  opy of the.**   
324d0 20 20 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72         D pointer
324e0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
324f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32500 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  on(D,X,N,E,P,F,S
32510 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,L)].**         
32520 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
32530 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44  ate_function16(D
32540 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
32550 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20   call that.**   
32560 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
32570 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
32580 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  on associated wi
32590 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  th [sqlite3_cont
325a0 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74  ext] C..*/.sqlit
325b0 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
325c0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
325d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
325e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
325f0 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
32600 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 32 37  iary Data {H1627
32610 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a  0} <S20200>.**.*
32620 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
32630 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
32640 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
32650 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
32660 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
32670 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
32680 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
32690 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
326a0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
326b0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
326c0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
326d0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
326e0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
326f0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
32700 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
32710 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
32720 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
32730 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
32740 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
32750 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
32760 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
32770 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
32780 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
32790 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
327a0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
327b0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
327c0 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
327d0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
327e0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
327f0 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
32800 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
32810 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
32820 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
32830 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
32840 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
32850 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
32860 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
32870 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
32880 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
32890 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
328a0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
328b0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
328c0 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
328d0 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
328e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
328f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
32900 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
32910 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
32920 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
32930 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
32940 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
32950 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
32960 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
32970 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
32980 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
32990 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
329a0 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20  function. If no 
329b0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
329c0 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
329d0 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
329e0 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
329f0 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
32a00 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
32a10 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
32a20 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
32a30 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
32a40 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
32a50 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
32a60 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
32a70 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
32a80 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
32a90 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32aa0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
32ab0 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61  saves the metada
32ac0 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ta.** pointed to
32ad0 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61   by its 3rd para
32ae0 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74  meter as the met
32af0 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  adata for the N-
32b00 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
32b10 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
32b20 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32b30 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a  on.  Subsequent.
32b40 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
32b50 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
32b60 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74  ) might return t
32b70 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20  his data, if it 
32b80 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20  has.** not been 
32b90 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66  destroyed..** If
32ba0 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c   it is not NULL,
32bb0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
32bc0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
32bd0 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67  or.** function g
32be0 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20  iven by the 4th 
32bf0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
32c00 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
32c10 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74  () on.** the met
32c20 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63  adata when the c
32c30 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
32c40 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
32c50 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68  changes.** or wh
32c60 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
32c70 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20  ment completes, 
32c80 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
32c90 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  first..**.** SQL
32ca0 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63  ite is free to c
32cb0 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74  all the destruct
32cc0 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61  or and drop meta
32cd0 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70  data on any.** p
32ce0 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20  arameter of any 
32cf0 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20  function at any 
32d00 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20  time.  The only 
32d10 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61  guarantee is tha
32d20 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63  t.** the destruc
32d30 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c  tor will be call
32d40 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65  ed before the me
32d50 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65  tadata is droppe
32d60 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63  d..**.** In prac
32d70 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
32d80 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
32d90 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
32da0 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73  ls for.** expres
32db0 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63  sions that are c
32dc0 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69  onstant at compi
32dd0 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e  le time. This in
32de0 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a  cludes literal.*
32df0 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c  * values and SQL
32e00 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a   variables..**.*
32e10 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
32e20 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
32e30 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
32e40 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
32e50 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32e60 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
32e70 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
32e80 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32 7d 20 54  **.** {H16272} T
32e90 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  he [sqlite3_get_
32ea0 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e  auxdata(C,N)] in
32eb0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
32ec0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20  a pointer.**    
32ed0 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64 61 74        to metadat
32ee0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
32ef0 68 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65  h the Nth parame
32f00 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ter of the SQL f
32f10 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  unction.**      
32f20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74 65 78      whose contex
32f30 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20  t is C, or NULL 
32f40 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  if there is no m
32f50 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
32f60 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ed.**          w
32f70 69 74 68 20 74 68 61 74 20 70 61 72 61 6d 65 74  ith that paramet
32f80 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37  er..**.** {H1627
32f90 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
32fa0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
32fb0 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  P,D)] interface 
32fc0 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61 64 61  assigns a metada
32fd0 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  ta.**          p
32fe0 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68 65 20  ointer P to the 
32ff0 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  Nth parameter of
33000 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
33010 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43  n with context C
33020 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 36 7d  ..**.** {H16276}
33030 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
33040 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
33050 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67  or D with a sing
33060 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20  le argument.**  
33070 20 20 20 20 20 20 20 20 77 68 69 63 68 20 69 73          which is
33080 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f   the metadata po
33090 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e  inter P followin
330a0 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20  g a call to.**  
330b0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
330c0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
330d0 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69  ,P,D)] when SQLi
330e0 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c  te ceases to hol
330f0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  d.**          th
33100 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a  e metadata..**.*
33110 2a 20 7b 48 31 36 32 37 37 7d 20 53 51 4c 69 74  * {H16277} SQLit
33120 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64  e ceases to hold
33130 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e   metadata for an
33140 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61   SQL function pa
33150 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20  rameter.**      
33160 20 20 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c      when the val
33170 75 65 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d  ue of that param
33180 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a  eter changes..**
33190 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20 57 68 65  .** {H16278} Whe
331a0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  n [sqlite3_set_a
331b0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d  uxdata(C,N,P,D)]
331c0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65   is invoked, the
331d0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20   destructor.**  
331e0 20 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65          is calle
331f0 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20  d for any prior 
33200 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
33210 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d  ted with the sam
33220 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  e function.**   
33230 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43         context C
33240 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e   and parameter N
33250 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 39 7d  ..**.** {H16279}
33260 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c   SQLite will cal
33270 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f  l destructors fo
33280 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69  r any metadata i
33290 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20  t is holding.** 
332a0 20 20 20 20 20 20 20 20 20 69 6e 20 61 20 70 61           in a pa
332b0 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72  rticular [prepar
332c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
332d0 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20  when either.**  
332e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
332f0 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73  _reset(S)] or [s
33300 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
33310 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a  S)] is called..*
33320 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
33330 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
33340 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
33350 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t N);.void sqlit
33360 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
33370 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33380 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
33390 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
333a0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
333b0 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
333c0 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
333d0 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
333e0 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31  r {H10280} <S301
333f0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
33400 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
33410 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
33420 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
33430 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
33440 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
33450 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
33460 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
33470 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74  t_blob()].  If t
33480 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
33490 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
334a0 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
334b0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
334c0 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
334d0 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
334e0 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
334f0 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
33500 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
33510 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53  royed.  The.** S
33520 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
33530 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
33540 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
33550 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
33560 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
33570 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
33580 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
33590 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
335a0 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
335b0 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
335c0 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
335d0 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
335e0 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
335f0 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
33600 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
33610 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20  C++ compilers.  
33620 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31  See ticket #2191
33630 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
33640 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
33650 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
33660 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
33670 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
33680 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
33690 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
336a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
336b0 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
336c0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
336d0 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
336e0 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
336f0 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
33700 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31  SQL Function {H1
33710 36 34 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6400} <S20200>.*
33720 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
33730 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
33740 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
33750 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
33760 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
33770 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
33780 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
33790 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
337a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
337b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
337c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
337d0 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
337e0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
337f0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
33800 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
33810 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
33820 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
33830 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
33840 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
33850 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
33860 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
33870 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
33880 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
33890 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
338a0 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
338b0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
338c0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
338d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
338e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
338f0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
33900 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
33910 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
33920 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33930 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
33940 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
33950 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
33960 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
33970 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
33980 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
33990 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
339a0 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
339b0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
339c0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
339d0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
339e0 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
339f0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
33a00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33a10 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33a20 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
33a30 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
33a40 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
33a50 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
33a60 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
33a70 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
33a80 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  rameter..**.** T
33a90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33aa0 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72  t_double() inter
33ab0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
33ac0 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
33ad0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33ae0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
33af0 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  be a floating po
33b00 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66  int value specif
33b10 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e  ied.** by its 2n
33b20 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
33b30 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
33b40 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
33b50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33b60 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
33b70 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
33b80 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
33b90 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
33ba0 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
33bb0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
33bc0 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
33bd0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
33be0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
33bf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33c00 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
33c10 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
33c20 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
33c30 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
33c40 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20  essage.  SQLite 
33c50 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
33c60 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
33c70 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
33c80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33c90 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c  () as UTF-8. SQL
33ca0 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
33cb0 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
33cc0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
33cd0 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
33ce0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
33cf0 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49  * byte order.  I
33d00 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
33d10 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
33d20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
33d30 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
33d40 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
33d50 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
33d60 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
33d70 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
33d80 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
33d90 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
33da0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
33db0 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69  r..** If the thi
33dc0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
33dd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33de0 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
33df0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33e00 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
33e10 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
33e20 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
33e30 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
33e40 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
33e50 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
33e60 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
33e70 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20  message..** The 
33e80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33e90 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
33ea0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
33eb0 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
33ec0 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
33ed0 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
33ee0 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
33ef0 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
33f00 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
33f10 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
33f20 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
33f30 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
33f40 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
33f50 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
33f60 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71   harm..** The sq
33f70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33f80 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
33f90 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
33fa0 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
33fb0 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
33fc0 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
33fd0 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
33fe0 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75  ction.  By defau
33ff0 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
34000 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
34010 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71  ERROR.  A subseq
34020 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
34030 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34040 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
34050 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
34060 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
34070 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
34080 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
34090 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
340a0 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  lt_toobig() inte
340b0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
340c0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
340d0 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
340e0 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
340f0 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20  g or BLOB is to 
34100 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
34110 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
34120 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65  ite3_result_nome
34130 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
34140 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
34150 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
34160 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
34170 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
34180 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
34190 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
341a0 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
341b0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
341c0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
341d0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
341e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
341f0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
34200 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
34210 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
34220 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
34230 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71  ument..** The sq
34240 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
34250 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
34260 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
34270 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
34280 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34290 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
342a0 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
342b0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
342c0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
342d0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
342e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
342f0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
34300 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
34310 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
34320 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
34330 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34340 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
34350 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  L..**.** The sql
34360 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
34370 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
34380 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
34390 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
343a0 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
343b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
343c0 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
343d0 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
343e0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
343f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
34400 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
34410 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
34420 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
34430 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
34440 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
34450 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
34460 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
34470 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
34480 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
34490 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
344a0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
344b0 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
344c0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
344d0 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
344e0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
344f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34500 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
34510 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  es..** If the 3r
34520 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
34530 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34540 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
34550 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
34560 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
34570 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
34580 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
34590 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
345a0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
345b0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
345c0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
345d0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
345e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
345f0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
34600 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
34610 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
34620 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
34630 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
34640 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
34650 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
34660 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
34670 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34680 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
34690 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  ion result..** I
346a0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
346b0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
346c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
346d0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
346e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
346f0 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
34700 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
34710 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
34720 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
34730 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
34740 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
34750 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
34760 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
34770 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
34780 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
34790 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
347a0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
347b0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
347c0 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69  faces or.** sqli
347d0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
347e0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
347f0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
34800 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
34810 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
34820 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
34830 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
34840 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
34850 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
34860 63 6f 70 79 20 74 68 65 20 69 74 20 6f 72 20 63  copy the it or c
34870 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
34880 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
34890 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
348a0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74   result..** If t
348b0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
348c0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
348d0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
348e0 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
348f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
34900 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
34910 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
34920 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
34930 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
34940 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
34950 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
34960 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
34970 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
34980 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
34990 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
349a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
349b0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
349c0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
349d0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
349e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
349f0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
34a00 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
34a10 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
34a20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34a30 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
34a40 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
34a50 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ter.  The.** sql
34a60 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
34a70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
34a80 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
34a90 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
34aa0 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
34ab0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34ac0 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
34ad0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
34ae0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
34af0 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
34b00 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
34b10 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
34b20 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
34b30 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73  * A [protected s
34b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34b50 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
34b60 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
34b70 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
34b80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
34b90 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
34ba0 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
34bb0 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
34bc0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
34bd0 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
34be0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
34bf0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
34c00 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
34c10 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
34c20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
34c30 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
34c40 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
34c50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34c60 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34c70 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
34c80 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
34c90 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
34ca0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
34cb0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
34cc0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
34cd0 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20 54 68 65  .** {H16403} The
34ce0 20 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20   default return 
34cf0 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53  value from any S
34d00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e  QL function is N
34d10 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ULL..**.** {H164
34d20 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
34d30 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
34d40 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
34d50 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
34d60 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
34d70 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
34d80 6e 20 43 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  n C to be a BLOB
34d90 20 74 68 61 74 20 69 73 20 4e 20 62 79 74 65 73   that is N bytes
34da0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
34db0 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20  length and with 
34dc0 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20  content pointed 
34dd0 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  to by V..**.** {
34de0 48 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c  H16409} The [sql
34df0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
34e00 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61  le(C,V)] interfa
34e10 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
34e20 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
34e30 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
34e40 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
34e50 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
34e60 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48  alue V..**.** {H
34e70 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  16412} The [sqli
34e80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34e90 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61  (C,V,N)] interfa
34ea0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
34eb0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
34ec0 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74    value of funct
34ed0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
34ee0 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
34ef0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
34f00 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
34f10 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 38 20  OR] and a UTF-8 
34f20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f  error message co
34f30 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74  pied from V up t
34f40 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
34f50 20 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74    first zero byt
34f60 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74  e or until N byt
34f70 65 73 20 61 72 65 20 72 65 61 64 20 69 66 20 4e  es are read if N
34f80 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a   is positive..**
34f90 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20 54 68 65  .** {H16415} The
34fa0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
34fb0 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d  _error16(C,V,N)]
34fc0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
34fd0 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
34fe0 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
34ff0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
35000 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
35010 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
35020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
35030 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20  LITE_ERROR] and 
35040 61 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  a UTF-16 native 
35050 62 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72  byte order error
35060 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20   message.**     
35070 20 20 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d       copied from
35080 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
35090 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
350a0 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79  or or until N by
350b0 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
350c0 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69 73  are read if N is
350d0 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a   positive..**.**
350e0 20 7b 48 31 36 34 31 38 7d 20 54 68 65 20 5b 73   {H16418} The [s
350f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35100 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69  ror_toobig(C)] i
35110 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
35120 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
35130 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
35140 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20   the function C 
35150 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
35160 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
35170 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  de.**          [
35180 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61  SQLITE_TOOBIG] a
35190 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  nd an appropriat
351a0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
351b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 31 7d 20  .**.** {H16421} 
351c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
351d0 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
351e0 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
351f0 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
35200 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
35210 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
35220 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
35230 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
35240 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
35250 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45      [SQLITE_NOME
35260 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70  M] and an approp
35270 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73  riate error mess
35280 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  age..**.** {H164
35290 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
352a0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
352b0 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61  de(C,E)] interfa
352c0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
352d0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
352e0 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
352f0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
35300 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
35310 68 20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a  h error code E..
35320 2a 2a 20 20 20 20 20 20 20 20 20 20 54 68 65 20  **          The 
35330 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
35340 78 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  xt is unchanged.
35350 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 37 7d 20  .**.** {H16427} 
35360 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
35370 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e  ult_int(C,V)] in
35380 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
35390 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
353a0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
353b0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
353c0 20 74 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65   the 32-bit inte
353d0 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a  ger value V..**.
353e0 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54 68 65 20  ** {H16430} The 
353f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35400 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65  int64(C,V)] inte
35410 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
35420 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
35430 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
35440 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
35450 68 65 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  he 64-bit intege
35460 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  r value V..**.**
35470 20 7b 48 31 36 34 33 33 7d 20 54 68 65 20 5b 73   {H16433} The [s
35480 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
35490 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ll(C)] interface
354a0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
354b0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
354c0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
354d0 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  n C to be NULL..
354e0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36 7d 20 54  **.** {H16436} T
354f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
35500 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29  lt_text(C,V,N,D)
35510 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
35520 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
35530 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
35540 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
35550 6f 20 62 65 20 74 68 65 20 55 54 46 2d 38 20 73  o be the UTF-8 s
35560 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
35570 20 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69    V up to the fi
35580 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73  rst zero if N is
35590 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20   negative.**    
355a0 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72        or the fir
355b0 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20  st N bytes of V 
355c0 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  if N is non-nega
355d0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tive..**.** {H16
355e0 34 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  439} The [sqlite
355f0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
35600 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
35610 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
35620 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
35630 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
35640 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
35650 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
35660 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
35670 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75        string V u
35680 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
35690 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61  ero if N is nega
356a0 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
356b0 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20   or the first N 
356c0 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20  bytes of V if N 
356d0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
356e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 32 7d 20  .**.** {H16442} 
356f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
35700 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56  ult_text16be(C,V
35710 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
35720 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
35730 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
35740 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
35750 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
35760 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a  F-16 big-endian.
35770 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
35780 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66  ng V up to the f
35790 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69  irst zero if N i
357a0 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20  s negative.**   
357b0 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69         or the fi
357c0 72 73 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56  rst N bytes or V
357d0 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67   if N is non-neg
357e0 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
357f0 36 34 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  6445} The [sqlit
35800 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35810 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74  le(C,V,N,D)] int
35820 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
35830 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
35840 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
35850 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
35860 74 68 65 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  the UTF-16 littl
35870 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20  e-endian.**     
35880 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70       string V up
35890 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
358a0 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  ro if N is negat
358b0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
358c0 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62  or the first N b
358d0 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69  ytes of V if N i
358e0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
358f0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38 7d 20 54  **.** {H16448} T
35900 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
35910 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20 69  lt_value(C,V)] i
35920 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
35930 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
35940 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
35950 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
35960 65 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  e the [unprotect
35970 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
35980 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  ].**          ob
35990 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ject V..**.** {H
359a0 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69  16451} The [sqli
359b0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
359c0 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66  lob(C,N)] interf
359d0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
359e0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
359f0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
35a00 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
35a10 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f 66 20 61  N-byte BLOB of a
35a20 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20  ll zeros..**.** 
35a30 7b 48 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71  {H16454} The [sq
35a40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35a50 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  or()] and [sqlit
35a60 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
35a70 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  6()].**         
35a80 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65   interfaces make
35a90 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72   a copy of their
35aa0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
35ab0 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a  trings before.**
35ac0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
35ad0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ing..**.** {H164
35ae0 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 65 73  57} If the D des
35af0 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65  tructor paramete
35b00 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  r to [sqlite3_re
35b10 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c  sult_blob(C,V,N,
35b20 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
35b30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35b40 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _text(C,V,N,D)],
35b50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35b60 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
35b70 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
35b80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35b90 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29  ext16be(C,V,N,D)
35ba0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
35bb0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
35bc0 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
35bd0 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73  ,D)] is the cons
35be0 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
35bf0 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  TIC].**         
35c00 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63   then no destruc
35c10 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c  tor is ever call
35c20 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65  ed on the pointe
35c30 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a  r V and SQLite.*
35c40 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 75 6d  *          assum
35c50 65 73 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d  es that V is imm
35c60 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  utable..**.** {H
35c70 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 44 20  16460} If the D 
35c80 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d  destructor param
35c90 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
35ca0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
35cb0 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
35cc0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
35cd0 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
35ce0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  )], [sqlite3_res
35cf0 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e  ult_text16(C,V,N
35d00 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
35d10 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
35d20 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
35d30 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
35d40 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
35d50 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
35d60 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63  V,N,D)] is the c
35d70 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20  onstant.**      
35d80 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e      [SQLITE_TRAN
35d90 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20  SIENT] then the 
35da0 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73  interfaces makes
35db0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
35dc0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65  *          conte
35dd0 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61  nt of V and reta
35de0 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a  ins the copy..**
35df0 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20 49 66 20  .** {H16463} If 
35e00 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72  the D destructor
35e10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
35e20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
35e30 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  ob(C,V,N,D)],.**
35e40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
35e50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43  e3_result_text(C
35e60 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74  ,V,N,D)], [sqlit
35e70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35e80 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
35e90 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
35ea0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
35eb0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a  (C,V,N,D)], or.*
35ec0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
35ed0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
35ee0 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73  6le(C,V,N,D)] is
35ef0 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65   some value othe
35f00 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  r than.**       
35f10 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73     the constants
35f20 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
35f30 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41   and [SQLITE_TRA
35f40 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a 20  NSIENT] then.** 
35f50 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20           SQLite 
35f60 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
35f70 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74  destructor D wit
35f80 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79 20  h V as its only 
35f90 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20  argument.**     
35fa0 20 20 20 20 20 77 68 65 6e 20 69 74 20 68 61 73       when it has
35fb0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
35fc0 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76  he V value..*/.v
35fd0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35fe0 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
35ff0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
36000 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
36010 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
36020 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36030 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
36040 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65  context*, double
36050 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36060 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c  result_error(sql
36070 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
36080 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
36090 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
360a0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
360b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
360c0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
360d0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
360e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
360f0 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
36100 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
36110 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36120 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63  _nomem(sqlite3_c
36130 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
36140 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36150 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33  ror_code(sqlite3
36160 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
36170 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36180 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
36190 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
361a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
361b0 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
361c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
361d0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69  ite3_int64);.voi
361e0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
361f0 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
36200 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
36210 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36220 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
36230 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
36240 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
36250 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
36260 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
36270 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
36280 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
36290 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
362a0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
362b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
362c0 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
362d0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
362e0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
362f0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
36300 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36310 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
36320 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
36330 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
36340 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
36350 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
36360 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
36370 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
36380 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
36390 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
363a0 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
363b0 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
363c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
363d0 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
363e0 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31  ng Sequences {H1
363f0 36 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a  6600} <S20300>.*
36400 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
36410 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f  ions are used to
36420 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69   add new collati
36430 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20  on sequences to 
36440 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
36450 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
36460 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
36470 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
36480 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
36490 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  the new collatio
364a0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70  n sequence is sp
364b0 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46  ecified as a UTF
364c0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
364d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
364e0 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
364f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36500 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
36510 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
36520 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33  ring for sqlite3
36530 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36540 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61  n16(). In all ca
36550 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  ses.** the name 
36560 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  is passed as the
36570 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
36580 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
36590 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
365a0 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ent may be one o
365b0 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20  f the constants 
365c0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
365d0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
365e0 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  E] or [SQLITE_UT
365f0 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16BE], indicati
36600 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72  ng that the user
36610 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75  -supplied.** rou
36620 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20  tine expects to 
36630 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65  be passed pointe
36640 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e  rs to strings en
36650 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
36660 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  8,.** UTF-16 lit
36670 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle-endian, or U
36680 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
36690 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
366a0 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67  The.** third arg
366b0 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f  ument might also
366c0 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
366d0 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e  6_ALIGNED] to in
366e0 64 69 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74  dicate that.** t
366f0 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63  he routine expec
36700 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31  ts pointers to 1
36710 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e  6-bit word align
36720 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66  ed strings.** of
36730 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
36740 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
36750 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d   of the host com
36760 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70  puter..**.** A p
36770 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73  ointer to the us
36780 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74  er supplied rout
36790 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73  ine must be pass
367a0 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a  ed as the fifth.
367b0 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66  ** argument.  If
367c0 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69   it is NULL, thi
367d0 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  s is the same as
367e0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
367f0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
36800 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c  nce (so that SQL
36810 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20  ite cannot call 
36820 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20  it anymore)..** 
36830 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70  Each time the ap
36840 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69  plication suppli
36850 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  ed function is i
36860 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61  nvoked, it is pa
36870 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66  ssed.** as its f
36880 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61  irst parameter a
36890 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
368a0 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  d* passed as the
368b0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
368c0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
368d0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
368e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
368f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
36900 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d  )..**.** The rem
36910 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73  aining arguments
36920 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
36930 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75  ion-supplied rou
36940 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72  tine are two str
36950 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65  ings,.** each re
36960 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28  presented by a (
36970 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61  length, data) pa
36980 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69  ir and encoded i
36990 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a  n the encoding.*
369a0 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65  * that was passe
369b0 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61  d as the third a
369c0 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65  rgument when the
369d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
369e0 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73  nce was.** regis
369f0 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68  tered. {END}  Th
36a00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
36a10 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
36a20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a  routine should.*
36a30 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76  * return negativ
36a40 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74  e, zero or posit
36a50 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73 74  ive if the first
36a60 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
36a70 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74  than,.** equal t
36a80 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  o, or greater th
36a90 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74  an the second st
36aa0 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49  ring. i.e. (STRI
36ab0 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a  NG1 - STRING2)..
36ac0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
36ad0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36ae0 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
36af0 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
36b00 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
36b10 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
36b20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61  takes an extra a
36b30 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
36b40 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
36b50 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  r.** the collati
36b60 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  on.  The destruc
36b70 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68  tor is called wh
36b80 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
36b90 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64   is.** destroyed
36ba0 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61   and is passed a
36bb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75   copy of the fou
36bc0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f  rth parameter vo
36bd0 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f  id* pointer.** o
36be0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  f the sqlite3_cr
36bf0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
36c00 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f  2()..** Collatio
36c10 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  ns are destroyed
36c20 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f   when they are o
36c30 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
36c40 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  er calls to the.
36c50 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  ** collation cre
36c60 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
36c70 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74  or when the [dat
36c80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36c90 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75  ] is closed.** u
36ca0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
36cb0 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ose()]..**.** IN
36cc0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
36cd0 7b 48 31 36 36 30 33 7d 20 41 20 73 75 63 63 65  {H16603} A succe
36ce0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68  ssful call to th
36cf0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
36d00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36d10 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
36d20 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,P,F,D)] interfa
36d30 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ce.**          r
36d40 65 67 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f  egisters functio
36d50 6e 20 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61  n F as the compa
36d60 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75  rison function u
36d70 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  sed to.**       
36d80 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c     implement col
36d90 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74 68 65 20  lation X on the 
36da0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36db0 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20  tion] B for.**  
36dc0 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
36dd0 73 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e  s having encodin
36de0 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  g E..**.** {H166
36df0 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72  04} SQLite under
36e00 73 74 61 6e 64 73 20 74 68 65 20 58 20 70 61 72  stands the X par
36e10 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
36e20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
36e30 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
36e40 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
36e50 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   as a zero-termi
36e60 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
36e70 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69    UTF-8 string i
36e80 6e 20 77 68 69 63 68 20 63 61 73 65 20 69 73 20  n which case is 
36e90 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49  ignored for ASCI
36ea0 49 20 63 68 61 72 61 63 74 65 72 73 20 61 6e 64  I characters and
36eb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
36ec0 73 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20  significant for 
36ed0 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63  non-ASCII charac
36ee0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ters..**.** {H16
36ef0 36 30 36 7d 20 53 75 63 63 65 73 73 69 76 65 20  606} Successive 
36f00 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
36f10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36f20 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
36f30 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D)].**          
36f40 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61  with the same va
36f50 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61  lues for B, X, a
36f60 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70  nd E, override p
36f70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20  rior values.**  
36f80 20 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c          of P, F,
36f90 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48   and D..**.** {H
36fa0 31 36 36 30 39 7d 20 49 66 20 74 68 65 20 64 65  16609} If the de
36fb0 73 74 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73  structor D in [s
36fc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36fd0 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
36fe0 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20  ,P,F,D)].**     
36ff0 20 20 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c       is not NULL
37000 20 74 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c   then it is call
37010 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
37020 20 50 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20   P when the.**  
37030 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
37040 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72  g function is dr
37050 6f 70 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e  opped by SQLite.
37060 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 32 7d 20  .**.** {H16612} 
37070 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
37080 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20  tion is dropped 
37090 77 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c  when it is overl
370a0 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  oaded..**.** {H1
370b0 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e  6615} A collatin
370c0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72  g function is dr
370d0 6f 70 70 65 64 20 77 68 65 6e 20 74 68 65 20 64  opped when the d
370e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
370f0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  on.**          i
37100 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
37110 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
37120 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 38 7d  ..**.** {H16618}
37130 20 54 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69   The pointer P i
37140 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  n [sqlite3_creat
37150 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
37160 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20  ,X,E,P,F,D)].** 
37170 20 20 20 20 20 20 20 20 20 69 73 20 70 61 73 73           is pass
37180 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
37190 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
371a0 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69  r to the compari
371b0 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  son.**          
371c0 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61  function F for a
371d0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
371e0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a  vocations of F..
371f0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31 7d 20 41  **.** {H16621} A
37200 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
37210 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37220 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69  on(B,X,E,P,F)] i
37230 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20  s exactly.**    
37240 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61        the same a
37250 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  s a call to [sql
37260 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37270 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68  ation_v2()] with
37280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
37290 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73   same parameters
372a0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74   and a NULL dest
372b0 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ructor..**.** {H
372c0 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67  16624} Following
372d0 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61   a [sqlite3_crea
372e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
372f0 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a  B,X,E,P,F,D)],.*
37300 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74  *          SQLit
37310 65 20 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61  e uses the compa
37320 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46  rison function F
37330 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f   for all text co
37340 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20  mparison.**     
37350 20 20 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20       operations 
37360 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
37370 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f   connection] B o
37380 6e 20 74 65 78 74 20 76 61 6c 75 65 73 20 74 68  n text values th
37390 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75  at.**          u
373a0 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  se the collating
373b0 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 64 20   sequence named 
373c0 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 37  X..**.** {H16627
373d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
373e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
373f0 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f  6(B,X,E,P,F)] wo
37400 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  rks the same.** 
37410 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c           as [sql
37420 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37430 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29  ation(B,X,E,P,F)
37440 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
37450 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
37460 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69  llation name X i
37470 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20  s understood as 
37480 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
37490 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20   byte order.**  
374a0 20 20 20 20 20 20 20 20 69 6e 73 74 65 61 64 20          instead 
374b0 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  of UTF-8..**.** 
374c0 7b 48 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75  {H16630} When mu
374d0 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f  ltiple compariso
374e0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  n functions are 
374f0 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68  available for th
37500 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
37510 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71     collating seq
37520 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68  uence, SQLite ch
37530 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68  ooses the one wh
37540 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  ose text encodin
37550 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  g.**          re
37560 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
37570 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65   amount of conve
37580 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64  rsion from the d
37590 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20  efault.**       
375a0 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67     text encoding
375b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
375c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
375d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
375e0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
375f0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
37600 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
37610 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
37620 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
37630 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
37640 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
37650 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
37660 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37670 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
37680 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
37690 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
376a0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
376b0 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
376c0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
376d0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
376e0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
376f0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
37700 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
37710 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
37720 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
37730 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
37740 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a  st void *zName,.
37750 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
37760 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
37770 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
37780 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
37790 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
377a0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
377b0 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
377c0 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
377d0 20 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30   {H16700} <S2030
377e0 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69  0>.**.** To avoi
377f0 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
37800 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
37810 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
37820 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
37830 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
37840 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
37850 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
37860 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
37870 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
37880 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
37890 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65   be called whene
378a0 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
378b0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
378c0 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72  quence is requir
378d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
378e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
378f0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
37900 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
37910 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
37920 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
37930 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
37940 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
37950 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
37960 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
37970 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
37980 2e 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71  . {H16703} If sq
37990 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
379a0 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
379b0 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73  ed,.** the names
379c0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
379d0 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
379e0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
379f0 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  er..** A call to
37a00 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
37a10 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78   replaces any ex
37a20 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e  isting callback.
37a30 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
37a40 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
37a50 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
37a60 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
37a70 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
37a80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
37a90 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
37aa0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
37ab0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
37ac0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
37ad0 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
37ae0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
37af0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
37b00 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68  nection.  The th
37b10 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
37b20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
37b30 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
37b40 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  F16BE],.** or [S
37b50 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
37b60 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
37b70 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
37b80 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
37b90 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
37ba0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
37bb0 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  d.  The fourth p
37bc0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
37bd0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
37be0 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
37bf0 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a  n sequence..**.*
37c00 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
37c10 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
37c20 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
37c30 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
37c40 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
37c50 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
37c60 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
37c70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
37c80 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
37c90 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37ca0 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  tion_v2()]..**.*
37cb0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
37cc0 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20 41 20 73  .** {H16702} A s
37cd0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
37ce0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  o [sqlite3_colla
37cf0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c  tion_needed(D,P,
37d00 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F)].**          
37d10 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  or [sqlite3_coll
37d20 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44  ation_needed16(D
37d30 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a  ,P,F)] causes.**
37d40 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64            the [d
37d50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37d60 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20  on] D to invoke 
37d70 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20  callback F with 
37d80 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  first.**        
37d90 20 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68    parameter P wh
37da0 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73 20  enever it needs 
37db0 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  a comparison fun
37dc0 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20  ction for a.**  
37dd0 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
37de0 67 20 73 65 71 75 65 6e 63 65 20 74 68 61 74 20  g sequence that 
37df0 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77  it does not know
37e00 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48   about..**.** {H
37e10 31 36 37 30 34 7d 20 45 61 63 68 20 73 75 63 63  16704} Each succ
37e20 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
37e30 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
37e40 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a  n_needed()] or.*
37e50 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
37e60 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37e70 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69  eded16()] overri
37e80 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  des the callback
37e90 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20   registered.**  
37ea0 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73          on the s
37eb0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
37ec0 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69  nnection] by pri
37ed0 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68  or calls to eith
37ee0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  er.**          i
37ef0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
37f00 7b 48 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d  {H16706} The nam
37f10 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 74  e of the request
37f20 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ed collating fun
37f30 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20  ction passed in 
37f40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
37f50 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
37f60 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
37f70 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65   in UTF-8 if the
37f80 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
37f90 20 20 20 20 20 20 77 61 73 20 72 65 67 69 73 74        was regist
37fa0 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ered using [sqli
37fb0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37fc0 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20  eded()] and.**  
37fd0 20 20 20 20 20 20 20 20 69 73 20 69 6e 20 55 54          is in UT
37fe0 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
37ff0 20 6f 72 64 65 72 20 69 66 20 74 68 65 20 63 61   order if the ca
38000 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20  llback was.**   
38010 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
38020 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
38030 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
38040 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  d16()]..*/.int s
38050 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
38060 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
38070 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
38080 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
38090 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
380a0 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
380b0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
380c0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
380d0 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
380e0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
380f0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
38100 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
38110 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
38120 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
38130 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
38140 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
38150 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
38160 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
38170 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
38180 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
38190 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
381a0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
381b0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
381c0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
381d0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
381e0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
381f0 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
38200 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
38210 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38220 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
38230 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
38240 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
38250 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
38260 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
38270 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
38280 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
38290 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
382a0 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
382b0 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
382c0 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
382d0 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
382e0 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
382f0 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
38300 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
38310 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
38320 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
38330 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
38340 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
38350 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
38360 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
38370 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
38380 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
38390 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
383a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
383b0 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
383c0 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
383d0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
383e0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
383f0 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
38400 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38410 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
38420 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
38430 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53  Time {H10530} <S
38440 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  40410>.**.** The
38450 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
38460 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
38470 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
38480 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
38490 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
384a0 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
384b0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
384c0 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
384d0 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
384e0 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61  .** If the opera
384f0 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
38500 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
38510 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
38520 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20  .** millisecond 
38530 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  time resolution,
38540 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77   then the time w
38550 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75  ill be rounded u
38560 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72  p to.** the near
38570 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20  est second. The 
38580 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
38590 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20  econds of sleep 
385a0 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75  actually.** requ
385b0 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  ested from the o
385c0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
385d0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
385e0 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
385f0 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
38600 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
38610 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
38620 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
38630 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
38640 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  s] object..**.**
38650 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
38660 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54 68 65 20  ** {H10533} The 
38670 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d  [sqlite3_sleep(M
38680 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76  )] interface inv
38690 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a  okes the xSleep.
386a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 74 68  **          meth
386b0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
386c0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56  t [sqlite3_vfs|V
386d0 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  FS] in order to.
386e0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 73 70  **          susp
386f0 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  end execution of
38700 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
38710 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74  ead for at least
38720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d  .**          M m
38730 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a  illiseconds..**.
38740 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54 68 65 20  ** {H10536} The 
38750 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d  [sqlite3_sleep(M
38760 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
38770 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
38780 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  of.**          m
38790 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
387a0 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65  leep actually re
387b0 71 75 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f  quested of the o
387c0 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20  perating.**     
387d0 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69       system, whi
387e0 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67  ch might be larg
387f0 65 72 20 74 68 61 6e 20 74 68 65 20 70 61 72 61  er than the para
38800 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20  meter M..*/.int 
38810 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
38820 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
38830 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
38840 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
38850 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20  Temporary Files 
38860 7b 48 31 30 33 31 30 7d 20 3c 53 32 30 30 30 30  {H10310} <S20000
38870 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20  >.**.** If this 
38880 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
38890 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
388a0 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
388b0 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
388c0 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
388d0 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a.