/ Hex Artifact Content
Login

Artifact 2be75cc1f2a5515db910e8d0e2d5954b493fd1f3:


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 33 39 39 20 32 30 30 38 2f 30  n,v 1.399 2008/0
05f0: 39 2f 32 32 20 31 37 3a 35 34 3a 34 36 20 64 72  9/22 17:54:46 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 6e 6f 6e 7a 65 72 6f 20 69 66  eturn nonzero if
1b10: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
1b20: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 20 20 20 20   only if.**     
1b30: 20 20 20 20 20 53 51 4c 69 74 65 20 77 61 73 20       SQLite was 
1b40: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
1b50: 65 20 69 74 73 20 6d 75 74 65 78 65 73 20 65 6e  e its mutexes en
1b60: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
1b70: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 31 30 32 7d  ..**.** {H10102}
1b80: 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
1b90: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
1ba0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
1bb0: 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  ] function.**   
1bc0: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 6e 6f 74         shall not
1bd0: 20 63 68 61 6e 67 65 20 77 68 65 6e 20 6d 75 74   change when mut
1be0: 65 78 20 73 65 74 74 69 6e 67 20 61 72 65 20 6d  ex setting are m
1bf0: 6f 64 69 66 69 65 64 20 61 74 0a 2a 2a 20 20 20  odified at.**   
1c00: 20 20 20 20 20 20 20 72 75 6e 74 69 6d 65 20 75         runtime u
1c10: 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
1c20: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
1c30: 72 66 61 63 65 20 61 6e 64 20 0a 2a 2a 20 20 20  rface and .**   
1c40: 20 20 20 20 20 20 20 65 73 70 65 63 69 61 6c 6c         especiall
1c50: 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  y the [SQLITE_CO
1c60: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
1c70: 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D],.**          
1c80: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
1c90: 55 4c 54 49 54 48 52 45 41 44 5d 2c 20 5b 53 51  ULTITHREAD], [SQ
1ca0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
1cb0: 41 4c 49 5a 45 44 5d 2c 0a 2a 2a 20 20 20 20 20  ALIZED],.**     
1cc0: 20 20 20 20 20 61 6e 64 20 5b 53 51 4c 49 54 45       and [SQLITE
1cd0: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 76  _CONFIG_MUTEX] v
1ce0: 65 72 62 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  erbs..*/.int sql
1cf0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
1d00: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
1d10: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
1d20: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
1d30: 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30  le {H12000} <S40
1d40: 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
1d50: 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  : {database conn
1d60: 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73  ection} {databas
1d70: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a  e connections}.*
1d80: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53  *.** Each open S
1d90: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69  QLite database i
1da0: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  s represented by
1db0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
1dc0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20   instance of.** 
1dd0: 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63  the opaque struc
1de0: 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69  ture named "sqli
1df0: 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65  te3".  It is use
1e00: 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20  ful to think of 
1e10: 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f  an sqlite3.** po
1e20: 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65  inter as an obje
1e30: 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ct.  The [sqlite
1e40: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1e50: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
1e60: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  nd.** [sqlite3_o
1e70: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
1e80: 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e  aces are its con
1e90: 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b  structors, and [
1ea0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1eb0: 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72  .** is its destr
1ec0: 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72  uctor.  There ar
1ed0: 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74  e many other int
1ee0: 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73  erfaces (such as
1ef0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1f00: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
1f10: 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
1f20: 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  tion()], and.** 
1f30: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1f40: 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65  meout()] to name
1f50: 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74   but three) that
1f60: 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20   are methods on 
1f70: 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62  an.** sqlite3 ob
1f80: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
1f90: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
1fa0: 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20  sqlite3;../*.** 
1fb0: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74  CAPI3REF: 64-Bit
1fc0: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b   Integer Types {
1fd0: 48 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e  H10200} <S10110>
1fe0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1ff0: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74  lite_int64 sqlit
2000: 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42  e_uint64.**.** B
2010: 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20  ecause there is 
2020: 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72  no cross-platfor
2030: 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79  m way to specify
2040: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
2050: 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20  types.** SQLite 
2060: 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66  includes typedef
2070: 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67  s for 64-bit sig
2080: 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64  ned and unsigned
2090: 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a   integers..**.**
20a0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   The sqlite3_int
20b0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75  64 and sqlite3_u
20c0: 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72  int64 are the pr
20d0: 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66  eferred type def
20e0: 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65  initions..** The
20f0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e   sqlite_int64 an
2100: 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  d sqlite_uint64 
2110: 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72  types are suppor
2120: 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ted for backward
2130: 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  s.** compatibili
2140: 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  ty only..**.** I
2150: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2160: 20 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b 73   {H10201} The [s
2170: 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64  qlite_int64] and
2180: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d   [sqlite3_int64]
2190: 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63   type shall spec
21a0: 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ify.**          
21b0: 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
21c0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
21d0: 48 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 6c  H10202} The [sql
21e0: 69 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20  ite_uint64] and 
21f0: 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d  [sqlite3_uint64]
2200: 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63   type shall spec
2210: 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ify.**          
2220: 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65  a 64-bit unsigne
2230: 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69  d integer..*/.#i
2240: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
2250: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
2260: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2270: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
2280: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
2290: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
22a0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
22b0: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
22c0: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
22d0: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
22e0: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
22f0: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
2300: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
2310: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
2320: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2330: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
2340: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
2350: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
2360: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
2370: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2380: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
2390: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
23a0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
23b0: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
23c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
23d0: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
23e0: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
23f0: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
2400: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
2410: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
2420: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
2430: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
2440: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
2450: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
2460: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
2470: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
2480: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
2490: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
24a0: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
24b0: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
24c0: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20  ection {H12010} 
24d0: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e  <S30100><S40200>
24e0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
24f0: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2500: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2510: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2520: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
2530: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
2540: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2550: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
2560: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2570: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2580: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
2590: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
25a0: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61  handles] associa
25b0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  ted with.** the 
25c0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
25d0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
25e0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
25f0: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65  e object..** The
2600: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2610: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tmt()] interface
2620: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2630: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70  locate all.** [p
2640: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2650: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  ts] associated w
2660: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
2670: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64  connection] if d
2680: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63  esired..** Typic
2690: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f  al code might lo
26a0: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ok like this:.**
26b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
26c0: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33  <pre>.** sqlite3
26d0: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a  _stmt *pStmt;.**
26e0: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d   while( (pStmt =
26f0: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74   sqlite3_next_st
2700: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b  mt(db, 0))!=0 ){
2710: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c  .** &nbsp;   sql
2720: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53  ite3_finalize(pS
2730: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f  tmt);.** }.** </
2740: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2750: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  >.**.** If [sqli
2760: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
2770: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
2780: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
2790: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
27a0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
27b0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
27c0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  back..**.** INVA
27d0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
27e0: 31 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 73  12011} A success
27f0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2800: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73  ite3_close(C)] s
2810: 68 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 65  hall destroy the
2820: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
2830: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2840: 6e 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a  n] object C..**.
2850: 2a 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73 75  ** {H12012} A su
2860: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
2870: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2880: 43 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  C)] shall return
2890: 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a   SQLITE_OK..**.*
28a0: 2a 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75 63  * {H12013} A suc
28b0: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
28c0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
28d0: 29 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 65  )] shall release
28e0: 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
28f0: 20 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 74   memory and syst
2900: 65 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 73  em resources ass
2910: 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 61  ociated with [da
2920: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2930: 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  n].**          C
2940: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 7d  ..**.** {H12014}
2950: 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   A call to [sqli
2960: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f 6e  te3_close(C)] on
2970: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2980: 6e 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 0a  nection] C that.
2990: 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 20  **          has 
29a0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 6e  one or more open
29b0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29c0: 6d 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 69  ments] shall fai
29d0: 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  l with.**       
29e0: 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55     an [SQLITE_BU
29f0: 53 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a  SY] error code..
2a00: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 41  **.** {H12015} A
2a10: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2a20: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72  3_close(C)] wher
2a30: 65 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  e C is a NULL po
2a40: 69 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 20  inter shall.**  
2a50: 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 53          return S
2a60: 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20  QLITE_OK..**.** 
2a70: 7b 48 31 32 30 31 39 7d 20 57 68 65 6e 20 5b 73  {H12019} When [s
2a80: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
2a90: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61   is invoked on a
2aa0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2ab0: 63 74 69 6f 6e 5d 20 43 0a 2a 2a 20 20 20 20 20  ction] C.**     
2ac0: 20 20 20 20 20 74 68 61 74 20 68 61 73 20 61 20       that has a 
2ad0: 70 65 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74  pending transact
2ae0: 69 6f 6e 2c 20 74 68 65 20 74 72 61 6e 73 61 63  ion, the transac
2af0: 74 69 6f 6e 20 73 68 61 6c 6c 20 62 65 0a 2a 2a  tion shall be.**
2b00: 20 20 20 20 20 20 20 20 20 20 72 6f 6c 6c 65 64            rolled
2b10: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53   back..**.** ASS
2b20: 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
2b30: 7b 41 31 32 30 31 36 7d 20 54 68 65 20 43 20 70  {A12016} The C p
2b40: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
2b50: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d  ite3_close(C)] m
2b60: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
2b70: 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
2b80: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
2b90: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2ba0: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
2bb0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f  .**          fro
2bc0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
2bd0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2be0: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  n16()], or.**   
2bf0: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2c00: 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
2c10: 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63  not previously c
2c20: 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  losed..*/.int sq
2c30: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69  lite3_close(sqli
2c40: 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  te3 *);../*.** T
2c50: 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61  he type for a ca
2c60: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e  llback function.
2c70: 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61  .** This is lega
2c80: 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65  cy and deprecate
2c90: 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64  d.  It is includ
2ca0: 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  ed for historica
2cb0: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  l.** compatibili
2cc0: 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f  ty and is not do
2cd0: 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70  cumented..*/.typ
2ce0: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74  edef int (*sqlit
2cf0: 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69  e3_callback)(voi
2d00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63  d*,int,char**, c
2d10: 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  har**);../*.** C
2d20: 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65  API3REF: One-Ste
2d30: 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f  p Query Executio
2d40: 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 32  n Interface {H12
2d50: 31 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a  100} <S10000>.**
2d60: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2d70: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
2d80: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 74   is a convenient
2d90: 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67 20   way of running 
2da0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53  one or more.** S
2db0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69  QL statements wi
2dc0: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
2dd0: 77 72 69 74 65 20 61 20 6c 6f 74 20 6f 66 20 43  write a lot of C
2de0: 20 63 6f 64 65 2e 20 20 54 68 65 20 55 54 46 2d   code.  The UTF-
2df0: 38 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 53 51 4c  8 encoded.** SQL
2e00: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2e10: 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
2e20: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2e30: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
2e40: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 74 61 74  c()..** The stat
2e50: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
2e60: 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20  ated one by one 
2e70: 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20  until either an 
2e80: 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e 20 69  error or.** an i
2e90: 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e 63 6f  nterrupt is enco
2ea0: 75 6e 74 65 72 65 64 2c 20 6f 72 20 75 6e 74 69  untered, or unti
2eb0: 6c 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64  l they are all d
2ec0: 6f 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70 61  one.  The 3rd pa
2ed0: 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 61 6e  rameter.** is an
2ee0: 20 6f 70 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61   optional callba
2ef0: 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ck that is invok
2f00: 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
2f10: 20 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72   row of any quer
2f20: 79 0a 2a 2a 20 72 65 73 75 6c 74 73 20 70 72 6f  y.** results pro
2f30: 64 75 63 65 64 20 62 79 20 74 68 65 20 53 51 4c  duced by the SQL
2f40: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68   statements.  Th
2f50: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
2f60: 74 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74  tells where.** t
2f70: 6f 20 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f  o write any erro
2f80: 72 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a  r messages..**.*
2f90: 2a 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * The error mess
2fa0: 61 67 65 20 70 61 73 73 65 64 20 62 61 63 6b 20  age passed back 
2fb0: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
2fc0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 68 65 6c  parameter is hel
2fd0: 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  d.** in memory o
2fe0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2ff0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
3000: 20 20 54 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d    To avoid a mem
3010: 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65  ory leak,.** the
3020: 20 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69 63 61   calling applica
3030: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61 6c 6c  tion should call
3040: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
3050: 5d 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72 0a 2a  ] on any error.*
3060: 2a 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e  * message return
3070: 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ed through the 5
3080: 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68 65  th parameter whe
3090: 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
30a0: 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 65  d using.** the e
30b0: 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
30c0: 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
30d0: 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
30e0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  2nd parameter is
30f0: 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74   NULL or an empt
3100: 79 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 20 61  y string.** or a
3110: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
3120: 6e 67 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ng only whitespa
3130: 63 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c  ce and comments,
3140: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20   then no SQL.** 
3150: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
3160: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
3170: 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
3180: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
3190: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
31a0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
31b0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 74  implemented in t
31c0: 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  erms of.** [sqli
31d0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
31e0: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
31f0: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
3200: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
3210: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
3220: 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  ec() routine doe
3230: 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74 68 65  s nothing to the
3240: 20 64 61 74 61 62 61 73 65 20 74 68 61 74 20 63   database that c
3250: 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a 2a  annot be done.**
3260: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
3270: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
3280: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
3290: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
32a0: 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ize()]..**.** IN
32b0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
32c0: 7b 48 31 32 31 30 31 7d 20 41 20 73 75 63 63 65  {H12101} A succe
32d0: 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
32e0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   of [sqlite3_exe
32f0: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 0a 2a 2a  c(D,S,C,A,E)].**
3300: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
3310: 73 65 71 75 65 6e 74 69 61 6c 6c 79 20 65 76 61  sequentially eva
3320: 6c 75 61 74 65 20 61 6c 6c 20 6f 66 20 74 68 65  luate all of the
3330: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
3340: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 65 6d 69  **          semi
3350: 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
3360: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
3370: 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
3380: 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
3390: 20 20 73 74 72 69 6e 67 20 53 20 77 69 74 68 69    string S withi
33a0: 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66  n the context of
33b0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
33c0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
33d0: 0a 2a 2a 20 7b 48 31 32 31 30 32 7d 20 49 66 20  .** {H12102} If 
33e0: 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20  the S parameter 
33f0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3400: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 20  (D,S,C,A,E)] is 
3410: 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  NULL then.**    
3420: 20 20 20 20 20 20 74 68 65 20 61 63 74 69 6f 6e        the action
3430: 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61  s of the interfa
3440: 63 65 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20  ce shall be the 
3450: 73 61 6d 65 20 61 73 20 69 66 20 74 68 65 0a 2a  same as if the.*
3460: 2a 20 20 20 20 20 20 20 20 20 20 53 20 70 61 72  *          S par
3470: 61 6d 65 74 65 72 20 77 65 72 65 20 61 6e 20 65  ameter were an e
3480: 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
3490: 2a 2a 20 7b 48 31 32 31 30 34 7d 20 54 68 65 20  ** {H12104} The 
34a0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
34b0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
34c0: 20 73 68 61 6c 6c 20 62 65 20 5b 53 51 4c 49 54   shall be [SQLIT
34d0: 45 5f 4f 4b 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20  E_OK] if all.** 
34e0: 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61           SQL sta
34f0: 74 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 63 63  tements run succ
3500: 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 74 6f 20  essfully and to 
3510: 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
3520: 2a 20 7b 48 31 32 31 30 35 7d 20 54 68 65 20 72  * {H12105} The r
3530: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b  eturn value of [
3540: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3550: 73 68 61 6c 6c 20 62 65 20 61 6e 20 61 70 70 72  shall be an appr
3560: 6f 70 72 69 61 74 65 0a 2a 2a 20 20 20 20 20 20  opriate.**      
3570: 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72      non-zero [er
3580: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
3590: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
35a0: 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ails..**.** {H12
35b0: 31 30 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20 6d  107} If one or m
35c0: 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73  ore of the SQL s
35d0: 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64  tatements handed
35e0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
35f0: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
3600: 20 72 65 74 75 72 6e 20 72 65 73 75 6c 74 73 20   return results 
3610: 61 6e 64 20 74 68 65 20 33 72 64 20 70 61 72 61  and the 3rd para
3620: 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  meter is not NUL
3630: 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  L, then.**      
3640: 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b      the callback
3650: 20 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66   function specif
3660: 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70  ied by the 3rd p
3670: 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20 62  arameter shall b
3680: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
3690: 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  voked once for e
36a0: 61 63 68 20 72 6f 77 20 6f 66 20 72 65 73 75 6c  ach row of resul
36b0: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 30  t..**.** {H12110
36c0: 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  } If the callbac
36d0: 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  k returns a non-
36e0: 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65 6e 20  zero value then 
36f0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3700: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
3710: 6c 6c 20 61 62 6f 72 74 20 74 68 65 20 53 51 4c  ll abort the SQL
3720: 20 73 74 61 74 65 6d 65 6e 74 20 69 74 20 69 73   statement it is
3730: 20 63 75 72 72 65 6e 74 6c 79 20 65 76 61 6c 75   currently evalu
3740: 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 20 20 20 20  ating,.**       
3750: 20 20 20 73 6b 69 70 20 61 6c 6c 20 73 75 62 73     skip all subs
3760: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
3770: 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65 74 75 72  ments, and retur
3780: 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  n [SQLITE_ABORT]
3790: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 33 7d  ..**.** {H12113}
37a0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
37b0: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  ec()] routine sh
37c0: 61 6c 6c 20 70 61 73 73 20 69 74 73 20 34 74 68  all pass its 4th
37d0: 20 70 61 72 61 6d 65 74 65 72 20 74 68 72 6f 75   parameter throu
37e0: 67 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  gh.**          a
37f0: 73 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  s the 1st parame
3800: 74 65 72 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ter of the callb
3810: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ack..**.** {H121
3820: 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  16} The [sqlite3
3830: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65  _exec()] routine
3840: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 32   shall set the 2
3850: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
3860: 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
3870: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 74  callback to be t
3880: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
3890: 75 6d 6e 73 20 69 6e 20 74 68 65 20 63 75 72 72  umns in the curr
38a0: 65 6e 74 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20  ent row of.**   
38b0: 20 20 20 20 20 20 20 72 65 73 75 6c 74 2e 0a 2a         result..*
38c0: 2a 0a 2a 2a 20 7b 48 31 32 31 31 39 7d 20 54 68  *.** {H12119} Th
38d0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
38e0: 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c  )] routine shall
38f0: 20 73 65 74 20 74 68 65 20 33 72 64 20 70 61 72   set the 3rd par
3900: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a  ameter of its.**
3910: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
3920: 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61  ck to be an arra
3930: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3940: 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67   strings holding
3950: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
3960: 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68   values for each
3970: 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
3980: 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73 65  urrent result se
3990: 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20  t row as.**     
39a0: 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72       obtained fr
39b0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
39c0: 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
39d0: 2a 20 7b 48 31 32 31 32 32 7d 20 54 68 65 20 5b  * {H12122} The [
39e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
39f0: 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65  routine shall se
3a00: 74 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  t the 4th parame
3a10: 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20  ter of its.**   
3a20: 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
3a30: 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f  to be an array o
3a40: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3a50: 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68  rings holding th
3a60: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61  e.**          na
3a70: 6d 65 73 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  mes of result co
3a80: 6c 75 6d 6e 73 20 61 73 20 6f 62 74 61 69 6e 65  lumns as obtaine
3a90: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
3aa0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3ab0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 35 7d 20 49  **.** {H12125} I
3ac0: 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
3ad0: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3ae0: 65 78 65 63 28 29 5d 20 69 73 20 4e 55 4c 4c 20  exec()] is NULL 
3af0: 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
3b00: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3b10: 5d 20 73 68 61 6c 6c 20 73 69 6c 65 6e 74 6c 79  ] shall silently
3b20: 20 64 69 73 63 61 72 64 20 71 75 65 72 79 20 72   discard query r
3b30: 65 73 75 6c 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  esults..**.** {H
3b40: 31 32 31 33 31 7d 20 49 66 20 61 6e 20 65 72 72  12131} If an err
3b50: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
3b60: 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75  parsing or evalu
3b70: 61 74 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 65  ating any of the
3b80: 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20   SQL.**         
3b90: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
3ba0: 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 6f  he S parameter o
3bb0: 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  f [sqlite3_exec(
3bc0: 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 61 6e 64 20  D,S,C,A,E)] and 
3bd0: 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  if.**          t
3be0: 68 65 20 45 20 70 61 72 61 6d 65 74 65 72 20 69  he E parameter i
3bf0: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
3c00: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3c10: 5d 20 73 68 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a  ] shall store.**
3c20: 20 20 20 20 20 20 20 20 20 20 69 6e 20 2a 45 20            in *E 
3c30: 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
3c40: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72 69  rror message wri
3c50: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
3c60: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20   obtained.**    
3c70: 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69        from [sqli
3c80: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
3c90: 2a 0a 2a 2a 20 7b 48 31 32 31 33 34 7d 20 54 68  *.** {H12134} Th
3ca0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
3cb0: 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 72 6f 75 74  D,S,C,A,E)] rout
3cc0: 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68  ine shall set th
3cd0: 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20  e value of.**   
3ce0: 20 20 20 20 20 20 20 2a 45 20 74 6f 20 4e 55 4c         *E to NUL
3cf0: 4c 20 69 66 20 45 20 69 73 20 6e 6f 74 20 4e 55  L if E is not NU
3d00: 4c 4c 20 61 6e 64 20 74 68 65 72 65 20 61 72 65  LL and there are
3d10: 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a   no errors..**.*
3d20: 2a 20 7b 48 31 32 31 33 37 7d 20 54 68 65 20 5b  * {H12137} The [
3d30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53  sqlite3_exec(D,S
3d40: 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74 69 6f  ,C,A,E)] functio
3d50: 6e 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20  n shall set the 
3d60: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20  [error code].** 
3d70: 20 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65 73           and mes
3d80: 73 61 67 65 20 61 63 63 65 73 73 69 62 6c 65 20  sage accessible 
3d90: 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
3da0: 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  code()],.**     
3db0: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72       [sqlite3_er
3dc0: 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71  rmsg()], and [sq
3dd0: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
3de0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 38  ]..**.** {H12138
3df0: 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d  } If the S param
3e00: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3e10: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3e20: 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a  ] is NULL or an.
3e30: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6d 70 74  **          empt
3e40: 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74  y string or cont
3e50: 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68  ains nothing oth
3e60: 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61  er than whitespa
3e70: 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a  ce, comments,.**
3e80: 20 20 20 20 20 20 20 20 20 20 61 6e 64 2f 6f 72            and/or
3e90: 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 65   semicolons, the
3ea0: 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 71  n results of [sq
3eb0: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
3ec0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
3ed0: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
3ee0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  , and [sqlite3_e
3ef0: 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20  rrmsg16()].**   
3f00: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73         shall res
3f10: 65 74 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e  et to indicate n
3f20: 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20  o errors..**.** 
3f30: 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
3f40: 2a 2a 20 7b 41 31 32 31 34 31 7d 20 54 68 65 20  ** {A12141} The 
3f50: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
3f60: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3f70: 28 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76  ()] must be an v
3f80: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a  alid and open.**
3f90: 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
3fa0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
3fb0: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 32 7d 20  .**.** {A12142} 
3fc0: 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
3fd0: 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
3fe0: 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65   be closed while
3ff0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
4000: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
4010: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
4020: 7b 41 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c  {A12143} The cal
4030: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
4040: 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65  ould use [sqlite
4050: 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65  3_free()] to fre
4060: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
4070: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65  e memory that *e
4080: 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f  rrmsg is left po
4090: 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74  inting at once t
40a0: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20  he error.**     
40b0: 20 20 20 20 20 6d 65 73 73 61 67 65 20 69 73 20       message is 
40c0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
40d0: 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 35 7d  ..**.** {A12145}
40e0: 20 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   The SQL stateme
40f0: 6e 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32  nt text in the 2
4100: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4110: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
4120: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73  .**          mus
4130: 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  t remain unchang
4140: 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ed while [sqlite
4150: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
4160: 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
4170: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
4180: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41a0: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
41b0: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
41c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
41d0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
41f0: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
4200: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
4210: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
4220: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
4230: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
4240: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
4250: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
4260: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4270: 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61          /* 1st a
4280: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
4290: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
42a0: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
42d0: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
42e0: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
42f0: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
4300: 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37  s {H10210} <S107
4310: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
4320: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
4330: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
4340: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
4350: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
4360: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
4370: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
4380: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
4390: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
43a0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
43b0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
43c0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
43d0: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
43e0: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
43f0: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
4400: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
4410: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
4420: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
4430: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
4440: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
4450: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
4460: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23  sult codes].*/.#
4470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
4480: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
4490: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
44a0: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
44b0: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
44c0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
44d0: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
44e0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
44f0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
4500: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
4510: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
4520: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
4530: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
4540: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
4550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
4560: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
4570: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
4580: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
4590: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
45a0: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
45b0: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
45c0: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
45d0: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
45e0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
45f0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
4600: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
4610: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4620: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
4630: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
4640: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
4650: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
4660: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4670: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
4680: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
4690: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
46a0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
46b0: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
46c0: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
46d0: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
46e0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
46f0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
4700: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
4710: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
4720: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
4730: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
4740: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
4750: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
4760: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
4770: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
4780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4790: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
47a0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
47b0: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
47c0: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
47d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
47e0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e  UND    12   /* N
47f0: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f  OT USED. Table o
4800: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
4810: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
4820: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
4830: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
4840: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
4850: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
4860: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
4870: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
4880: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
4890: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
48a0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
48b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
48c0: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
48d0: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61  NOT USED. Databa
48e0: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
48f0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
4900: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
4910: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
4920: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
4930: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4940: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
4950: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4960: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
4970: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4980: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
4990: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
49a0: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
49b0: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
49c0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
49d0: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
49e0: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
49f0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
4a00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a10: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
4a20: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
4a30: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
4a50: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
4a60: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
4a70: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
4a80: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
4a90: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
4aa0: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
4ab0: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
4ac0: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
4ad0: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
4ae0: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
4af0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
4b00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b10: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
4b20: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
4b30: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
4b40: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
4b50: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
4b60: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
4b70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
4b80: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
4b90: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
4ba0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
4bb0: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
4bc0: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
4bd0: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
4be0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
4bf0: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
4c00: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
4c10: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
4c20: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
4c30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4c40: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
4c50: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
4c60: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
4c70: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
4c80: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
4c90: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
4ca0: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
4cb0: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
4cc0: 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30  {H10220} <S10700
4cd0: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
4ce0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
4cf0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
4d00: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4d10: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4d20: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
4d30: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4d40: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4d50: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4d60: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4d70: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4d80: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4d90: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
4da0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
4db0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
4dc0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
4dd0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
4de0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
4df0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4e00: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4e10: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4e20: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4e30: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4e40: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4e50: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4e60: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4e70: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4e80: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4e90: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4ea0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
4eb0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
4ec0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
4ed0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
4ee0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
4ef0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4f00: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4f10: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4f20: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
4f30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4f40: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4f50: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4f60: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4f70: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4f80: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4f90: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4fa0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
4fb0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
4fc0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
4fd0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4fe0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
4ff0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
5000: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
5010: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
5020: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
5030: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
5040: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
5050: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
5060: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
5070: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
5080: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
5090: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
50a0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
50b0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
50c0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
50d0: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
50e0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
50f0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
5100: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
5110: 6f 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  o..**.** INVARIA
5120: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  NTS:.**.** {H102
5130: 32 33 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63  23} The symbolic
5140: 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74   name for an ext
5150: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
5160: 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 73  e shall contains
5170: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72  .**          a r
5180: 65 6c 61 74 65 64 20 70 72 69 6d 61 72 79 20 72  elated primary r
5190: 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20  esult code as a 
51a0: 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48  prefix..**.** {H
51b0: 31 30 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72  10224} Primary r
51c0: 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73  esult code names
51d0: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 61   shall contain a
51e0: 20 73 69 6e 67 6c 65 20 22 5f 22 20 63 68 61 72   single "_" char
51f0: 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  acter..**.** {H1
5200: 30 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20 72  0225} Extended r
5210: 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73  esult code names
5220: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 74   shall contain t
5230: 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63  wo or more "_" c
5240: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
5250: 20 7b 48 31 30 32 32 36 7d 20 54 68 65 20 6e 75   {H10226} The nu
5260: 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61  meric value of a
5270: 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
5280: 74 20 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e  t code shall con
5290: 74 61 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  tain the.**     
52a0: 20 20 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c       numeric val
52b0: 75 65 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73  ue of its corres
52c0: 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20  ponding primary 
52d0: 72 65 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a  result code in.*
52e0: 2a 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6c  *          its l
52f0: 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
5300: 20 38 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66   8 bits..*/.#def
5310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5320: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
5330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5340: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5350: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5360: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
5370: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5380: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5390: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
53a0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
53b0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
53c0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
53d0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
53e0: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
53f0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5400: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5420: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5440: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5450: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
5460: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
5470: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
5480: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5490: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
54a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
54b0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
54c0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54d0: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
54e0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
54f0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
5500: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5510: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
5520: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5530: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
5540: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5550: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
5560: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5570: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
5580: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5590: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
55a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55b0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
55c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
55d0: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
55e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
55f0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
5600: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5610: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
5620: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5630: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
5640: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5650: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
5660: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
5670: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
5680: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5690: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
56a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
56b0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
56c0: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
56d0: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
56e0: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
56f0: 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 31  ns {H10230} <H11
5700: 31 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a  120> <H12700>.**
5710: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
5720: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
5730: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
5740: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
5750: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5760: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
5770: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
5780: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
5790: 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  er to the xOpen 
57a0: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a  method of the.**
57b0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
57c0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
57d0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  e SQLITE_OPEN_RE
57e0: 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30  ADONLY         0
57f0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
5800: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  e SQLITE_OPEN_RE
5810: 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30  ADWRITE        0
5820: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
5830: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  e SQLITE_OPEN_CR
5840: 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30  EATE           0
5850: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
5860: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45  e SQLITE_OPEN_DE
5870: 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30  LETEONCLOSE    0
5880: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
5890: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
58a0: 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30  CLUSIVE        0
58b0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
58c0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
58d0: 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30  IN_DB          0
58e0: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
58f0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45  e SQLITE_OPEN_TE
5900: 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30  MP_DB          0
5910: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
5920: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52  e SQLITE_OPEN_TR
5930: 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30  ANSIENT_DB     0
5940: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
5950: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
5960: 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30  IN_JOURNAL     0
5970: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
5980: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45  e SQLITE_OPEN_TE
5990: 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30  MP_JOURNAL     0
59a0: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
59b0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55  e SQLITE_OPEN_SU
59c0: 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30  BJOURNAL       0
59d0: 78 30 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e  x00002000.#defin
59e0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
59f0: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30  STER_JOURNAL   0
5a00: 78 30 30 30 30 34 30 30 30 0a 23 64 65 66 69 6e  x00004000.#defin
5a10: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f  e SQLITE_OPEN_NO
5a20: 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30  MUTEX          0
5a30: 78 30 30 30 30 38 30 30 30 0a 23 64 65 66 69 6e  x00008000.#defin
5a40: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55  e SQLITE_OPEN_FU
5a50: 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30  LLMUTEX        0
5a60: 78 30 30 30 31 30 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00010000../*.**
5a70: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
5a80: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
5a90: 73 20 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 31  s {H10240} <H111
5aa0: 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  20>.**.** The xD
5ab0: 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65  eviceCapabilitie
5ac0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
5ad0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5ae0: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
5af0: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
5b00: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
5b10: 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65  tor of the these
5b20: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
5b30: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
5b40: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
5b50: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
5b60: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
5b70: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
5b80: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
5b90: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
5ba0: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
5bb0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
5bc0: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
5bd0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
5be0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
5bf0: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
5c00: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
5c10: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
5c20: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
5c30: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
5c40: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
5c50: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
5c60: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
5c70: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
5c80: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
5c90: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
5ca0: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
5cb0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
5cc0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
5cd0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
5ce0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
5cf0: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
5d00: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
5d10: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
5d20: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
5d30: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
5d40: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
5d50: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
5d60: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
5d70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
5d80: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
5d90: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
5da0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
5db0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
5dc0: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
5dd0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
5de0: 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66  Write()..*/.#def
5df0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5e00: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
5e10: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
5e20: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5e30: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
5e40: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
5e50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5e60: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
5e70: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
5e80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5e90: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
5ea0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
5eb0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5ec0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
5ed0: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
5ee0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5ef0: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
5f00: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
5f10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5f20: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
5f30: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
5f40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5f50: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
5f60: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5f70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5f80: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
5f90: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
5fa0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5fb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
5fc0: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
5fd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5fe0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
5ff0: 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a   0x00000400../*.
6000: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
6010: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
6020: 20 7b 48 31 30 32 35 30 7d 20 3c 48 31 31 31 32   {H10250} <H1112
6030: 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a  0> <H11310>.**.*
6040: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
6050: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
6060: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6070: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
6080: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
6090: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
60a0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
60b0: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
60c0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
60d0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
60e0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
60f0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6100: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6110: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6120: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6130: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6140: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
6150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6160: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
6170: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
6180: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6190: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
61a0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
61b0: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
61c0: 61 67 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 31  ags {H10260} <H1
61d0: 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  1120>.**.** When
61e0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
61f0: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
6200: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
6210: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6220: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
6230: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
6240: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
6250: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6260: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
6270: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6280: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6290: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
62a0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
62b0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
62c0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
62d0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
62e0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
62f0: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
6300: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
6310: 62 65 20 66 6c 75 73 68 65 64 2e 20 54 68 65 20  be flushed. The 
6320: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6330: 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a  AL flag means.**
6340: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66   to use normal f
6350: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73  sync() semantics
6360: 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  . The SQLITE_SYN
6370: 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e  C_FULL flag mean
6380: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20  s.** to use Mac 
6390: 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS-X style fulls
63a0: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
63b0: 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  sync()..*/.#defi
63c0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  ne SQLITE_SYNC_N
63d0: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30  ORMAL        0x0
63e0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
63f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20  ITE_SYNC_FULL   
6400: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23         0x00003.#
6410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6420: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20  NC_DATAONLY     
6430: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20   0x00010../*.** 
6440: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6450: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65  erface Open File
6460: 20 48 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d   Handle {H11110}
6470: 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S20110>.**.** 
6480: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
6490: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
64a0: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
64b0: 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e   in the OS.** in
64c0: 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20  terface layer.  
64d0: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
64e0: 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e  terface implemen
64f0: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
6500: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
6510: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
6520: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
6530: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
6540: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
6550: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
6560: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
6570: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
6580: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6590: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
65a0: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
65b0: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
65c0: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
65d0: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
65e0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
65f0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
6600: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
6610: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
6620: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
6630: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
6640: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
6650: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
6660: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
6670: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
6680: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
6690: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
66a0: 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31  thods Object {H1
66b0: 31 31 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a  1120} <S20110>.*
66c0: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20  *.** Every file 
66d0: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73  opened by the [s
66e0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65  qlite3_vfs] xOpe
66f0: 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74  n method populat
6700: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  es an.** [sqlite
6710: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28  3_file] object (
6720: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c  or, more commonl
6730: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66  y, a subclass of
6740: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
6750: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77  _file] object) w
6760: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ith a pointer to
6770: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
6780: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  this object..** 
6790: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  This object defi
67a0: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20  nes the methods 
67b0: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20  used to perform 
67c0: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f  various operatio
67d0: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68  ns.** against th
67e0: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72  e open file repr
67f0: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b  esented by the [
6800: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6810: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ject..**.** The 
6820: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
6830: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
6840: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
6850: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
6860: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
6870: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
6880: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
6890: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
68a0: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
68b0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 2d 58  ce is a Mac OS-X
68c0: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
68d0: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
68e0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
68f0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
6900: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
6910: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
6920: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
6930: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
6940: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
6950: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
6960: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6970: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
6980: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
6990: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
69a0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
69b0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
69c0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
69d0: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
69e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
69f0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
6a00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6a10: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
6a20: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
6a30: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
6a40: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
6a50: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
6a60: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
6a70: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
6a80: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
6a90: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
6aa0: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
6ab0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
6ac0: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
6ad0: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
6ae0: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
6af0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
6b00: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
6b10: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
6b20: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
6b30: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
6b40: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
6b50: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
6b60: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
6b70: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
6b80: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
6b90: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
6ba0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
6bb0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
6bc0: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
6bd0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
6be0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
6bf0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
6c00: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
6c10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6c20: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
6c30: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
6c40: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
6c50: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
6c60: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
6c70: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
6c80: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
6c90: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
6ca0: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
6cb0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
6cc0: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
6cd0: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
6ce0: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
6cf0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
6d00: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
6d10: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
6d20: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
6d30: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
6d40: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
6d50: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
6d60: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
6d70: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
6d80: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
6d90: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
6da0: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
6db0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
6dc0: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
6dd0: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
6de0: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
6df0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
6e00: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
6e10: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
6e20: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
6e30: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
6e40: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
6e50: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
6e60: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
6e70: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
6e80: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
6e90: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
6ea0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
6eb0: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
6ec0: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
6ed0: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
6ee0: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a  id conflicts..**
6ef0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
6f00: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
6f10: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
6f20: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
6f30: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
6f40: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
6f50: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
6f60: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
6f70: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
6f80: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
6f90: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
6fa0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
6fb0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
6fc0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
6fd0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
6fe0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
6ff0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7000: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
7010: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
7020: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
7030: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7040: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7050: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7060: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7070: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
7080: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7090: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
70a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
70b0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
70c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
70d0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
70e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
70f0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7100: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7110: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
7120: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7130: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
7140: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7150: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
7160: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7170: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
7180: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7190: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
71a0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
71b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
71c0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
71d0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
71e0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
71f0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
7200: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7210: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
7220: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
7230: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
7240: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
7250: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
7260: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
7270: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
7280: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
7290: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
72a0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
72b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
72c0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
72d0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
72e0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
72f0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
7300: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
7310: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
7320: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
7330: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
7340: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
7350: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
7360: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
7370: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
7380: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
7390: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
73a0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
73b0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
73c0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
73d0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
73e0: 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
73f0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
7400: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
7410: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
7420: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
7430: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
7440: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
7450: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
7460: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
7470: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
7480: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
7490: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
74a0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
74b0: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
74c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
74d0: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
74e0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
74f0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
7500: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
7510: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
7520: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
7530: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
7540: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7550: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
7560: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
7570: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
7580: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
7590: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
75a0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
75b0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
75c0: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
75d0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
75e0: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
75f0: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
7600: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
7610: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
7620: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
7630: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7640: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
7650: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
7660: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
7670: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
7680: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
7690: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
76a0: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69  ile*);.  /* Addi
76b0: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
76c0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
76d0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
76e0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
76f0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
7700: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
7710: 64 65 73 20 7b 48 31 31 33 31 30 7d 20 3c 53 33  des {H11310} <S3
7720: 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0800>.**.** Thes
7730: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
7740: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
7750: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
7760: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
7770: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
7780: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7790: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
77a0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
77b0: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
77c0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ace..**.** The [
77d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
77e0: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
77f0: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
7800: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
7810: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
7820: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7830: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
7840: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
7850: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
7860: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
7870: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
7880: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
7890: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
78a0: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
78b0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
78c0: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
78d0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
78e0: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
78f0: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
7900: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
7910: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
7920: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
7930: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
7940: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
7950: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
7960: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  n SQLITE_TEST.**
7970: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a   is defined..*/.
7980: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
7990: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
79a0: 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43        1../*.** C
79b0: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
79c0: 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c  andle {H17110} <
79d0: 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20130>.**.** Th
79e0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
79f0: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
7a00: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
7a10: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
7a20: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
7a30: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
7a40: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
7a50: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
7a60: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
7a70: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
7a80: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
7a90: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
7aa0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
7ab0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
7ac0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
7ad0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
7ae0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
7af0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
7b00: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
7b10: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
7b20: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
7b30: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
7b40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7b50: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
7b60: 6a 65 63 74 20 7b 48 31 31 31 34 30 7d 20 3c 53  ject {H11140} <S
7b70: 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20  20100>.**.** An 
7b80: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
7b90: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7ba0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
7bb0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
7bc0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
7bd0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
7be0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
7bf0: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
7c00: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
7c10: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
7c20: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
7c30: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
7c40: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
7c50: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
7c60: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
7c70: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
7c80: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
7c90: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
7ca0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
7cb0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
7cc0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
7cd0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
7ce0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
7cf0: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
7d00: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
7d10: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
7d20: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
7d30: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
7d40: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
7d50: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
7d60: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
7d70: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
7d80: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
7d90: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
7da0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
7db0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
7dc0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
7dd0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
7de0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
7df0: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
7e00: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
7e10: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
7e20: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
7e30: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
7e40: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
7e50: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
7e60: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
7e70: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
7e80: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
7e90: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
7ea0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
7eb0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
7ec0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
7ed0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
7ee0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
7ef0: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
7f00: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
7f10: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
7f20: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
7f30: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
7f40: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
7f50: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
7f60: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
7f70: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
7f80: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
7f90: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7fa0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
7fb0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
7fc0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
7fd0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
7fe0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
7ff0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
8000: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
8010: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
8020: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
8030: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
8040: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
8050: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
8060: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
8070: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
8080: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
8090: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
80a0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
80b0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
80c0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
80d0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
80e0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
80f0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
8100: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
8110: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
8120: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
8130: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
8140: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
8150: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
8160: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 31 7d 20 53  **.** {H11141} S
8170: 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61  QLite will guara
8180: 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46  ntee that the zF
8190: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
81a0: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
81b0: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
81c0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
81d0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
81e0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
81f0: 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72 74 68  ).  SQLite furth
8200: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
8210: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
8220: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
8230: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
8240: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
8250: 2a 20 63 61 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20  * called. {END} 
8260: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
8270: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 73  previous sentens
8280: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
8290: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
82a0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
82b0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
82c0: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
82d0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
82e0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
82f0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
8300: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
8310: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f   parameter is xO
8320: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
8330: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
8340: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69 74 65 20  .** must invite 
8350: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
8360: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
8370: 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74  ile.  Whenever t
8380: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
8390: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
83a0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
83b0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
83c0: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
83d0: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
83e0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
83f0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8400: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 32 7d  ..**.** {H11142}
8410: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
8420: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
8430: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
8440: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
8450: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
8460: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
8470: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
8480: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
8490: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
84a0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
84b0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
84c0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
84d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
84e0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
84f0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
8500: 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f 70 65  {END}.** If xOpe
8510: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
8520: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
8530: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
8540: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
8550: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
8560: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
8570: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
8580: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
8590: 2a 0a 2a 2a 20 7b 48 31 31 31 34 33 7d 20 53 51  *.** {H11143} SQ
85a0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
85b0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
85c0: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
85d0: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
85e0: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
85f0: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
8600: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
8610: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
8620: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
8630: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
8640: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
8650: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
8660: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8670: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
8680: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
8690: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
86a0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
86b0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
86c0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
86d0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
86e0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
86f0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
8700: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  JOURNAL].** </ul
8710: 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  > {END}.**.** Th
8720: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
8730: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
8740: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
8750: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
8760: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
8770: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
8780: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
8790: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
87a0: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
87b0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
87c0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
87d0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
87e0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
87f0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
8800: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
8810: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
8820: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
8830: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
8840: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
8850: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
8860: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
8870: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
8880: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
8890: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
88a0: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
88b0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
88c0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
88d0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
88e0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
88f0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
8900: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
8910: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
8920: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
8930: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
8940: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
8950: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
8960: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
8970: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
8980: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8990: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
89a0: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
89b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
89c0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
89d0: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 35 7d 20 54  **.** {H11145} T
89e0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
89f0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
8a00: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
8a10: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
8a20: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
8a30: 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 48 31 31  is closed.  {H11
8a40: 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49 54 45  146} The [SQLITE
8a50: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
8a60: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
8a70: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61  set for TEMP  da
8a80: 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c  tabases, journal
8a90: 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75  s and for subjou
8aa0: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  rnals..**.** {H1
8ab0: 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54  1147} The [SQLIT
8ac0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
8ad0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
8ae0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
8af0: 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78  opened.** for ex
8b00: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20  clusive access. 
8b10: 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65   This flag is se
8b20: 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20  t for all files 
8b30: 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68  except.** for th
8b40: 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
8b50: 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  file..**.** {H11
8b60: 31 34 38 7d 20 41 74 20 6c 65 61 73 74 20 73 7a  148} At least sz
8b70: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
8b80: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
8b90: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
8ba0: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
8bb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
8bc0: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
8bd0: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
8be0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8bf0: 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 78 4f 70  . {END}  The xOp
8c00: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
8c10: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
8c20: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
8c30: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
8c40: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
8c50: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 39 7d 20  .**.** {H11149} 
8c60: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
8c70: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
8c80: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
8c90: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
8ca0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
8cb0: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
8cc0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
8cd0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
8ce0: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
8cf0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
8d00: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
8d10: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
8d20: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
8d30: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
8d40: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
8d50: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 7b  east readable. {
8d60: 45 4e 44 7d 20 20 54 68 65 20 66 69 6c 65 20 63  END}  The file c
8d70: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
8d80: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  tory..**.** {H11
8d90: 31 35 30 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  150} SQLite will
8da0: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
8db0: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
8dc0: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
8dd0: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
8de0: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
8df0: 61 6d 65 2e 20 7b 48 31 31 31 35 31 7d 20 54 68  ame. {H11151} Th
8e00: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
8e10: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
8e20: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
8e30: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
8e40: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
8e50: 6f 64 73 2e 20 7b 45 4e 44 7d 20 20 49 66 20 74  ods. {END}  If t
8e60: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
8e70: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
8e80: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
8e90: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
8ea0: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
8eb0: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
8ec0: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
8ed0: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
8ee0: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
8ef0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
8f00: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
8f10: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
8f20: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
8f30: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
8f40: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
8f50: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
8f60: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
8f70: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
8f80: 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  ime() interfaces
8f90: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69  .** are not stri
8fa0: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
8fb0: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
8fc0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
8fd0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
8fe0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
8ff0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
9000: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
9010: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
9020: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
9030: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
9040: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
9050: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
9060: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
9070: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
9080: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
9090: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
90a0: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
90b0: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
90c0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
90d0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
90e0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
90f0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
9100: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
9110: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68  conds given.  Th
9120: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
9130: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
9140: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
9150: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
9160: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
9170: 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  time..*/.typedef
9180: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
9190: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
91a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
91b0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
91c0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
91d0: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
91e0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  rsion number */.
91f0: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
9200: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
9210: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
9220: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
9230: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
9240: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
9250: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
9260: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
9270: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
9280: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
9290: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
92a0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
92b0: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
92c0: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
92d0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
92e0: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
92f0: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
9300: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
9310: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
9320: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
9330: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
9340: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
9350: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
9360: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
9370: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
9380: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
9390: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
93a0: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
93b0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
93c0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
93d0: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
93e0: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
93f0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
9400: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
9410: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
9420: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
9430: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
9440: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
9450: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
9460: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
9470: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
9480: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
9490: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
94a0: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
94b0: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
94c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
94d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
94e0: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Msg);.  void *(*
94f0: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
9500: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
9510: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
9520: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
9530: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
9540: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
9550: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
9560: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
9570: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
9580: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
9590: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
95a0: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
95b0: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
95c0: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
95d0: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
95e0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
95f0: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
9600: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
9610: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77  har *);.  /* New
9620: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
9630: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
9640: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
9650: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
9660: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
9670: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
9680: 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b  s happens. */.};
9690: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
96a0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
96b0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
96c0: 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 31  od {H11190} <H11
96d0: 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31  140>.**.** {H111
96e0: 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67 65  91} These intege
96f0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
9700: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
9710: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
9720: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
9730: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
9740: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
9750: 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20  ct. {END}  They 
9760: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
9770: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
9780: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
9790: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
97a0: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 7b 48 31 31  ing for..** {H11
97b0: 31 39 32 7d 20 57 69 74 68 20 53 51 4c 49 54 45  192} With SQLITE
97c0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
97d0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
97e0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
97f0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
9800: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
9810: 7b 48 31 31 31 39 33 7d 20 57 69 74 68 20 53 51  {H11193} With SQ
9820: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
9830: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
9840: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
9850: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
9860: 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61  file is both rea
9870: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
9880: 6c 65 2e 0a 2a 2a 20 7b 48 31 31 31 39 34 7d 20  le..** {H11194} 
9890: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
98a0: 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63  SS_READ, the xAc
98b0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
98c0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
98d0: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
98e0: 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  le..*/.#define S
98f0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
9900: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
9910: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
9920: 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 69  EADWRITE 1.#defi
9930: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
9940: 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a  _READ      2../*
9950: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
9960: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
9970: 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30  ite Library {H10
9980: 31 33 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33  130} <S20000><S3
9990: 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0100>.**.** The 
99a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
99b0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
99c0: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
99d0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
99e0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
99f0: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
9a00: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
9a10: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
9a20: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
9a30: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
9a40: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  ialize()..**.** 
9a50: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
9a60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
9a70: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
9a80: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
9a90: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
9aa0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9ab0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
9ac0: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
9ad0: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
9ae0: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
9af0: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
9b00: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
9b10: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
9b20: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
9b30: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
9b40: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f  3_shutdown().  O
9b50: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
9b60: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
9b70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9b80: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
9b90: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
9ba0: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
9bb0: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
9bc0: 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  s..**.** Among o
9bd0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71 6c  ther things, sql
9be0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9bf0: 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  ) shall invoke.*
9c00: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
9c10: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
9c20: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
9c30: 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76  n().** shall inv
9c40: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
9c50: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nd()..**.** The 
9c60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9c70: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
9c80: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f  urns SQLITE_OK o
9c90: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66  n success..** If
9ca0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
9cb0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
9cc0: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
9cd0: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
9ce0: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
9cf0: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
9d00: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
9d10: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
9d20: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
9d30: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
9d40: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
9d50: 20 6f 74 68 65 72 20 74 68 61 6e 20 53 51 4c 49   other than SQLI
9d60: 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  TE_OK..**.** The
9d70: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9d80: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
9d90: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
9da0: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
9db0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
9dc0: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
9dd0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
9de0: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
9df0: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
9e00: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9e10: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
9e20: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
9e30: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
9e40: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
9e50: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
9e60: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
9e70: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
9e80: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
9e90: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
9ea0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
9eb0: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
9ec0: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
9ed0: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
9ee0: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c   However, if SQL
9ef0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
9f00: 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
9f10: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 0a 2a 2a  OMIT_AUTOINIT.**
9f20: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
9f30: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
9f40: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
9f50: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
9f60: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
9f70: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
9f80: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
9f90: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
9fa0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
9fb0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
9fc0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
9fd0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
9fe0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
9ff0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
a000: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
a010: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
a020: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
a030: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a040: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
a050: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
a060: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
a070: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
a080: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
a090: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
a0a0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
a0b0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
a0c0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
a0d0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
a0e0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
a0f0: 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  th SQLITE_OMIT_A
a100: 55 54 4f 49 4e 49 54 20 6d 69 67 68 74 20 62 65  UTOINIT might be
a110: 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
a120: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
a130: 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
a140: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
a150: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
a160: 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
a170: 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
a180: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
a190: 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
a1a0: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
a1b0: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
a1c0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
a1d0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
a1e0: 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
a1f0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a200: 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
a210: 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
a220: 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
a230: 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
a240: 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
a250: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
a260: 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
a270: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
a280: 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
a290: 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
a2a0: 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
a2b0: 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
a2c0: 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
a2d0: 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
a2e0: 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
a2f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
a300: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
a310: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
a320: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
a330: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
a340: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
a350: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
a360: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
a370: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
a380: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
a390: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a3a0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
a3b0: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
a3c0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a3d0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
a3e0: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
a3f0: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
a400: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
a410: 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
a420: 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
a430: 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
a440: 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
a450: 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
a460: 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
a470: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
a480: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a490: 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
a4a0: 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
a4b0: 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
a4c0: 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73  or unix, windows
a4d0: 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68  , or os/2..** Wh
a4e0: 65 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68  en built for oth
a4f0: 65 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73  er platforms (us
a500: 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
a510: 53 5f 4f 54 48 45 52 3d 31 20 63 6f 6d 70 69 6c  S_OTHER=1 compil
a520: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
a530: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
a540: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
a550: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
a560: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
a570: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a580: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
a590: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
a5a0: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
a5b0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a5c0: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
a5d0: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
a5e0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
a5f0: 73 74 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  st return SQLITE
a600: 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 61  _OK on success a
a610: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
a620: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
a630: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
a640: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
a650: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
a660: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
a670: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
a680: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
a690: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
a6a0: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
a6b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
a6c0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
a6d0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48  QLite Library {H
a6e0: 31 30 31 34 35 7d 20 3c 53 32 30 30 30 30 3e 3c  10145} <S20000><
a6f0: 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S30200>.** EXPER
a700: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
a710: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
a720: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
a730: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
a740: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
a750: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
a760: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
a770: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
a780: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
a790: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
a7a0: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
a7b0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
a7c0: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
a7d0: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
a7e0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
a7f0: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
a800: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
a810: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
a820: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
a830: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
a840: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
a850: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
a860: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
a870: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
a880: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
a890: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
a8a0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
a8b0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
a8c0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
a8d0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
a8e0: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
a8f0: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
a900: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a910: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
a920: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
a930: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
a940: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
a950: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
a960: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
a970: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
a980: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a990: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
a9a0: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
a9b0: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
a9c0: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
a9d0: 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  hat sqlite3_conf
a9e0: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
a9f0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
aa00: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
aa10: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
aa20: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
aa30: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
aa40: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
aa50: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
aa60: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
aa70: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
aa80: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
aa90: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
aaa0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
aab0: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
aac0: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
aad0: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
aae0: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
aaf0: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
ab00: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
ab10: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
ab20: 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
ab30: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
ab40: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
ab50: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
ab60: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ab70: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63  ..**.** When a c
ab80: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ab90: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
aba0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
abb0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  urns SQLITE_OK..
abc0: 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  ** If the option
abd0: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
abe0: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
abf0: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
ac00: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
ac10: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
ac20: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
ac30: 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54   code]..*/.SQLIT
ac40: 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
ac50: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
ac60: 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
ac70: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
ac80: 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
ac90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48   connections  {H
aca0: 31 30 31 38 30 7d 20 3c 53 32 30 30 30 30 3e 0a  10180} <S20000>.
acb0: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
acc0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
acd0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
ace0: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
acf0: 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72  to make configur
ad00: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
ad10: 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20   to a [database 
ad20: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
ad30: 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  e interface is s
ad40: 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71  imilar to.** [sq
ad50: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
ad60: 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20  except that the 
ad70: 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f  changes apply to
ad80: 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61   a single.** [da
ad90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ada0: 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e  n] (specified in
adb0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
adc0: 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71  ent).  The.** sq
add0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
ade0: 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
adf0: 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d 6d  only be used imm
ae00: 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a 2a  ediately after.*
ae10: 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
ae20: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72 65  onnection is cre
ae30: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
ae40: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20  te3_open()],.** 
ae50: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
ae60: 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )], or [sqlite3_
ae70: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a  open_v2()].  .**
ae80: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
ae90: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
aea0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
aeb0: 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
aec0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
aed0: 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  erb - an integer
aee0: 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69 63   code that indic
aef0: 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73 70  ates what.** asp
af00: 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
af10: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
af20: 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
af30: 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c  ured..** The onl
af40: 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 69  y choice for thi
af50: 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c 49  s value is [SQLI
af60: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
af70: 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76  ASIDE]..** New v
af80: 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 20  erbs are likely 
af90: 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  to be added in f
afa0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
afb0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64  f SQLite..** Add
afc0: 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
afd0: 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65 20  s depend on the 
afe0: 76 65 72 62 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  verb..*/.SQLITE_
aff0: 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
b000: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
b010: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
b020: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
b030: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
b040: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
b050: 75 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20  utines {H10155} 
b060: 3c 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45  <S20120>.** EXPE
b070: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41  RIMENTAL.**.** A
b080: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
b090: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
b0a0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
b0b0: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
b0c0: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
b0d0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b0e0: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
b0f0: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
b100: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
b110: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
b120: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
b130: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
b140: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
b150: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
b160: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
b170: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
b180: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
b190: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
b1a0: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
b1b0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
b1c0: 20 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e    By creating an
b1d0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
b1e0: 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
b1f0: 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
b200: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
b210: 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
b220: 61 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70  ation, an.** app
b230: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
b240: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
b250: 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ive memory alloc
b260: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a  ation subsystem.
b270: 2a 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  ** for SQLite to
b280: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
b290: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
b2a0: 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
b2b0: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
b2c0: 20 63 6f 6d 65 73 20 77 69 74 68 20 61 20 62 75   comes with a bu
b2d0: 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
b2e0: 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 69 73 0a  locator that is.
b2f0: 2a 2a 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  ** perfectly ade
b300: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
b310: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
b320: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
b330: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
b340: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
b350: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
b360: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
b370: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
b380: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
b390: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
b3a0: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
b3b0: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
b3c0: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
b3d0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
b3e0: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
b3f0: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
b400: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
b410: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
b420: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
b430: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
b440: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
b450: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
b460: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
b470: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
b480: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
b490: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
b4a0: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20  ** The xMalloc, 
b4b0: 78 46 72 65 65 2c 20 61 6e 64 20 78 52 65 61 6c  xFree, and xReal
b4c0: 6c 6f 63 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  loc methods must
b4d0: 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a   work like the.*
b4e0: 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65  * malloc(), free
b4f0: 28 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28  (), and realloc(
b500: 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
b510: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69   the standard li
b520: 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  brary..**.** xSi
b530: 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
b540: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
b550: 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
b560: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
b570: 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
b580: 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
b590: 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
b5a0: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
b5b0: 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
b5c0: 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
b5d0: 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
b5e0: 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
b5f0: 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
b600: 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
b610: 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
b620: 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
b630: 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
b640: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b650: 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
b660: 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
b670: 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
b680: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
b690: 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
b6a0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
b6b0: 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
b6c0: 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
b6d0: 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
b6e0: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
b6f0: 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
b700: 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
b710: 20 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   of 2..**.** The
b720: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
b730: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
b740: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
b750: 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (For example,.*
b760: 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
b770: 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
b780: 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
b790: 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
b7a0: 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
b7b0: 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
b7c0: 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
b7d0: 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
b7e0: 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
b7f0: 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
b800: 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
b810: 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
b820: 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
b830: 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
b840: 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
b850: 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
b860: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
b870: 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
b880: 6f 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  own..*/.typedef 
b890: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
b8a0: 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
b8b0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
b8c0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
b8d0: 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
b8e0: 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
b8f0: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
b900: 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
b910: 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
b920: 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
b930: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
b940: 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
b950: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
b960: 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
b970: 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
b980: 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
b990: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
b9a0: 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
b9b0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
b9c0: 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
b9d0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
b9e0: 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
b9f0: 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
ba00: 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
ba10: 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
ba20: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
ba30: 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
ba40: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
ba50: 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
ba60: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
ba70: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
ba80: 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
ba90: 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
baa0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
bab0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
bac0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
bad0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
bae0: 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
baf0: 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
bb00: 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
bb10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
bb20: 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
bb30: 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d 20  ptions {H10160} 
bb40: 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45  <S20000>.** EXPE
bb50: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
bb60: 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
bb70: 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
bb80: 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
bb90: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
bba0: 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
bbb0: 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
bbc0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
bbd0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
bbe0: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
bbf0: 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
bc00: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
bc10: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
bc20: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
bc30: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
bc40: 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
bc50: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
bc60: 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
bc70: 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
bc80: 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
bc90: 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
bca0: 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
bcb0: 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
bcc0: 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
bcd0: 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
bce0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
bcf0: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
bd00: 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
bd10: 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
bd20: 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
bd30: 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
bd40: 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
bd50: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
bd60: 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
bd70: 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
bd80: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
bd90: 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
bda0: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
bdb0: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
bdc0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54   this option.  T
bdd0: 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62  his option disab
bde0: 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
bdf0: 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
be00: 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
be10: 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
be20: 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
be30: 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
be40: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
be50: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
be60: 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
be70: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
be80: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
be90: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
bea0: 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c  is option disabl
beb0: 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
bec0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
bed0: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
bee0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
bef0: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
bf00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
bf10: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
bf20: 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
bf30: 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
bf40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
bf50: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
bf60: 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
bf70: 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
bf80: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
bf90: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
bfa0: 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
bfb0: 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
bfc0: 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
bfd0: 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
bfe0: 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
bff0: 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
c000: 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
c010: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
c020: 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
c030: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
c040: 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f 63  ing mode].** doc
c050: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
c060: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
c070: 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ation.</dd>.**.*
c080: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
c090: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
c0a0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
c0b0: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
c0c0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
c0d0: 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 65  .  This option e
c0e0: 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
c0f0: 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
c100: 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
c110: 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
c120: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
c130: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
c140: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
c150: 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
c160: 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
c170: 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
c180: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
c190: 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
c1a0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
c1b0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
c1c0: 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
c1d0: 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
c1e0: 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
c1f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
c200: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
c210: 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
c220: 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
c230: 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
c240: 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
c250: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
c260: 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
c270: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
c280: 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
c290: 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
c2a0: 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 53   same time..** S
c2b0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
c2c0: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
c2d0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
c2e0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
c2f0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
c300: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
c310: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
c320: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
c330: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
c340: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
c350: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
c360: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
c370: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
c380: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
c390: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
c3a0: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
c3b0: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
c3c0: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
c3d0: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
c3e0: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
c3f0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
c400: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
c410: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
c420: 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a  to SQLite.</dd>.
c430: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
c440: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
c450: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  C</dt>.** <dd>Th
c460: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
c470: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
c480: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
c490: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
c4a0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
c4b0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
c4c0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
c4d0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
c4e0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
c4f0: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
c500: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
c510: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
c520: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
c530: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20  utines..** This 
c540: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
c550: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
c560: 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
c570: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
c580: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
c590: 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
c5a0: 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
c5b0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
c5c0: 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
c5d0: 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
c5e0: 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a  r example.</dd>.
c5f0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
c600: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
c610: 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  S</dt>.** <dd>Th
c620: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
c630: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
c640: 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74  of type int, int
c650: 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a  erpreted as a .*
c660: 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  * boolean, which
c670: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
c680: 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74  bles the collect
c690: 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ion of memory al
c6a0: 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61  location .** sta
c6b0: 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20 64 69  tistics. When di
c6c0: 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
c6d0: 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
c6e0: 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 0a  erfaces become .
c6f0: 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  ** non-operation
c700: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
c710: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
c720: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
c730: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
c740: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
c750: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
c760: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
c770: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  eap_limit()].** 
c780: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
c790: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
c7a0: 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  /ul>.** </dd>.**
c7b0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
c7c0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
c7d0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
c7e0: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
c7f0: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
c800: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
c810: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
c820: 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
c830: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
c840: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
c850: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
c860: 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 73  memory, the.** s
c870: 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
c880: 74 63 68 20 62 75 66 66 65 72 20 28 73 7a 29 2c  tch buffer (sz),
c890: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
c8a0: 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29 2e 20  of buffers (N). 
c8b0: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
c8c0: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
c8d0: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68  ltiple of 16. Th
c8e0: 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73  e sz parameter s
c8f0: 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62  hould be a few b
c900: 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74  ytes.** larger t
c910: 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73  han the actual s
c920: 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71  cratch space req
c930: 75 69 72 65 64 20 64 75 65 20 69 6e 74 65 72 6e  uired due intern
c940: 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20  al overhead..** 
c950: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
c960: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
c970: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
c980: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
c990: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
c9a0: 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  mory..** SQLite 
c9b0: 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65  will use no more
c9c0: 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
c9d0: 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e 63 65  h buffer at once
c9e0: 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 6f 0a   per thread, so.
c9f0: 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73  ** N should be s
ca00: 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 63 74  et to the expect
ca10: 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ed maximum numbe
ca20: 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20 54  r of threads.  T
ca30: 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65 74  he sz.** paramet
ca40: 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 20 74  er should be 6 t
ca50: 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 6f 66  imes the size of
ca60: 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
ca70: 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
ca80: 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 66 66  .** Scratch buff
ca90: 65 72 73 20 61 72 65 20 75 73 65 64 20 61 73 20  ers are used as 
caa0: 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 72 65  part of the btre
cab0: 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 61 74  e balance operat
cac0: 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65 20  ion.  If.** The 
cad0: 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 20 6e  btree balancer n
cae0: 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20  eeds additional 
caf0: 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
cb00: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
cb10: 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 75 66  y.** scratch buf
cb20: 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 73 63  fers or if no sc
cb30: 72 61 74 63 68 20 62 75 66 66 65 72 20 73 70 61  ratch buffer spa
cb40: 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  ce is specified,
cb50: 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
cb60: 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
cb70: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f 62  _malloc()] to ob
cb80: 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
cb90: 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a  it needs.</dd>.*
cba0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
cbb0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
cbc0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
cbd0: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
cbe0: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
cbf0: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
cc00: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
cc10: 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
cc20: 65 20 70 61 67 65 20 63 61 63 68 65 2e 20 20 54  e page cache.  T
cc30: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
cc40: 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e  rguments: A poin
cc50: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 6d 65  ter to the.** me
cc60: 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f  mory, the size o
cc70: 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66  f each page buff
cc80: 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
cc90: 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
cca0: 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
ccb0: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
ccc0: 20 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20   a power of two 
ccd0: 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
cce0: 33 32 37 36 38 2e 20 20 54 68 65 20 66 69 72 73  32768.  The firs
ccf0: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
cd00: 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
cd10: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
cd20: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
cd30: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
cd40: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
cd50: 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
cd60: 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ided by the firs
cd70: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61  t argument to sa
cd80: 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d  tisfy its.** mem
cd90: 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68  ory needs for th
cda0: 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20  e first N pages 
cdb0: 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20  that it adds to 
cdc0: 63 61 63 68 65 2e 20 20 49 66 20 61 64 64 69 74  cache.  If addit
cdd0: 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
cde0: 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
cdf0: 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
ce00: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
ce10: 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
ce20: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
ce30: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
ce40: 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
ce50: 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
ce60: 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
ce70: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
ce80: 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20  ight use one or 
ce90: 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75  more of the N bu
cea0: 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a  ffers to hold .*
ceb0: 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74  * memory account
cec0: 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  ing information.
ced0: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
cee0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
cef0: 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
cf00: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
cf10: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
cf20: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
cf30: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
cf40: 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e.** for all of 
cf50: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
cf60: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
cf70: 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  eds beyond those
cf80: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
cf90: 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
cfa0: 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20  IG_SCRATCH] and 
cfb0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
cfc0: 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
cfd0: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
cfe0: 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74  guments: A point
cff0: 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
d000: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  , the number of.
d010: 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
d020: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
d030: 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
d040: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20  llocation size. 
d050: 20 49 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   If.** the first
d060: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
d070: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
d080: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
d090: 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
d0a0: 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
d0b0: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
d0c0: 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
d0d0: 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
d0e0: 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
d0f0: 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
d100: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
d110: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
d120: 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20  OC].  If the.** 
d130: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
d140: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
d150: 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
d160: 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
d170: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
d180: 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
d190: 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
d1a0: 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
d1b0: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
d1c0: 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
d1d0: 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
d1e0: 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
d1f0: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f  ocation needs.</
d200: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
d210: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
d220: 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  X</dt>.** <dd>Th
d230: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
d240: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
d250: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
d260: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
d270: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
d280: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
d290: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
d2a0: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
d2b0: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
d2c0: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
d2d0: 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
d2e0: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
d2f0: 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
d300: 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
d310: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64   into SQLite.</d
d320: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
d330: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
d340: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
d350: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
d360: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
d370: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
d380: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
d390: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
d3a0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
d3b0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
d3c0: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
d3d0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
d3e0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
d3f0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
d400: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
d410: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
d420: 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  nes..** This opt
d430: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
d440: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
d450: 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
d460: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
d470: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
d480: 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
d490: 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
d4a0: 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
d4b0: 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
d4c0: 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
d4d0: 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  le.</dd>.**.** <
d4e0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
d4f0: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
d500: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
d510: 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
d520: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
d530: 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
d540: 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63  t.** memory allc
d550: 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20  ation lookaside 
d560: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54  optimization.  T
d570: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
d580: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
d590: 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
d5a0: 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
d5b0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
d5c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
d5d0: 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
d5e0: 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
d5f0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f  se connection.</
d600: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
d610: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d620: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
d630: 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
d640: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d650: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
d660: 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
d670: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
d680: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
d690: 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
d6a0: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
d6b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
d6c0: 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
d6d0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d6e0: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
d6f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
d700: 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
d710: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
d720: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
d730: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d740: 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
d750: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
d760: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
d770: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
d780: 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
d790: 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
d7a0: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
d7b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d7c0: 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
d7d0: 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
d7e0: 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
d7f0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
d800: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
d810: 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
d820: 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
d830: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d840: 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
d850: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
d860: 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
d870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d880: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
d890: 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
d8a0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
d8b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d8c0: 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
d8d0: 4f 43 20 20 20 31 32 20 20 2f 2a 20 69 6e 74 20  OC   12  /* int 
d8e0: 74 68 72 65 73 68 6f 6c 64 20 2a 2f 0a 23 64 65  threshold */.#de
d8f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d900: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
d910: 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
d920: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
d930: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
d940: 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 37 30   Options {H10170
d950: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
d960: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
d970: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
d980: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
d990: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
d9a0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
d9b0: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
d9c0: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
d9d0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
d9e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
d9f0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
da00: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
da10: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
da20: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
da30: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
da40: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
da50: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
da60: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
da70: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
da80: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
da90: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
daa0: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
dab0: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
dac0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
dad0: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
dae0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
daf0: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
db00: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
db10: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
db20: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
db30: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
db40: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
db50: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
db60: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
db70: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
db80: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
db90: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
dba0: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
dbb0: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
dbc0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
dbd0: 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
dbe0: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
dbf0: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
dc00: 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
dc10: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
dc20: 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
dc30: 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
dc40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
dc50: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
dc60: 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
dc70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
dc80: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
dc90: 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
dca0: 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
dcb0: 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
dcc0: 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
dcd0: 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
dce0: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62  * argument may b
dcf0: 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
dd00: 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
dd10: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6c 6f   allocate the lo
dd20: 6f 6b 61 73 69 64 65 0a 2a 2a 20 62 75 66 66 65  okaside.** buffe
dd30: 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
dd40: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
dd50: 5d 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ].  The second a
dd60: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
dd70: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
dd80: 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
dd90: 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 74 68 69  slot and the thi
dda0: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
ddb0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
ddc0: 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
ddd0: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
dde0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
ddf0: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
de00: 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
de10: 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
de20: 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
de30: 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
de40: 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  uments.</dd>.**.
de50: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
de60: 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
de70: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
de80: 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
de90: 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a  int int */.../*.
dea0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
deb0: 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
dec0: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
ded0: 6f 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53  odes {H12200} <S
dee0: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10700>.**.** The
def0: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
df00: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
df10: 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
df20: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
df30: 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
df40: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
df50: 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54  ure of SQLite. T
df60: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
df70: 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
df80: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
df90: 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
dfa0: 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
dfb0: 20 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e   considerations.
dfc0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
dfd0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 31  S:.**.** {H12201
dfe0: 7d 20 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61  } Each new [data
dff0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
e000: 20 73 68 61 6c 6c 20 68 61 76 65 20 74 68 65 0a   shall have the.
e010: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74  **          [ext
e020: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
e030: 65 73 5d 20 66 65 61 74 75 72 65 20 64 69 73 61  es] feature disa
e040: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
e050: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 32 7d 20  .**.** {H12202} 
e060: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  The [sqlite3_ext
e070: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
e080: 65 73 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61  es(D,F)] interfa
e090: 63 65 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a  ce shall enable.
e0a0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74  **          [ext
e0b0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
e0c0: 65 73 5d 20 66 6f 72 20 74 68 65 20 20 5b 64 61  es] for the  [da
e0d0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e0e0: 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] D.**         
e0f0: 20 69 66 20 74 68 65 20 46 20 70 61 72 61 6d 65   if the F parame
e100: 74 65 72 20 69 73 20 74 72 75 65 2c 20 6f 72 20  ter is true, or 
e110: 64 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20  disable them if 
e120: 46 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69  F is false..*/.i
e130: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
e140: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
e150: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
e160: 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
e170: 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
e180: 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32  ert Rowid {H1222
e190: 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
e1a0: 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20  * Each entry in 
e1b0: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
e1c0: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
e1d0: 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
e1e0: 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
e1f0: 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68   the "rowid". Th
e200: 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
e210: 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
e220: 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
e230: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
e240: 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
e250: 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
e260: 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
e270: 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
e280: 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
e290: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
e2a0: 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
e2b0: 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
e2c0: 74 79 70 65 20 49 4e 54 45 47 45 52 20 50 52 49  type INTEGER PRI
e2d0: 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68  MARY KEY then th
e2e0: 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
e2f0: 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
e300: 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
e310: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
e320: 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69  returns the rowi
e330: 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  d of the most re
e340: 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
e350: 75 6c 20 49 4e 53 45 52 54 20 69 6e 74 6f 20 74  ul INSERT into t
e360: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
e370: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
e380: 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  onnection].** in
e390: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
e3a0: 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63  ent.  If no succ
e3b0: 65 73 73 66 75 6c 20 49 4e 53 45 52 54 73 0a 2a  essful INSERTs.*
e3c0: 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
e3d0: 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74  rred on that dat
e3e0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e3f0: 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  , zero is return
e400: 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
e410: 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20 77 69  INSERT occurs wi
e420: 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
e430: 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f  then the rowid o
e440: 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
e450: 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65  * row is returne
e460: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
e470: 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  e as long as the
e480: 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e   trigger is runn
e490: 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
e4a0: 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72   the trigger ter
e4b0: 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c  minates, the val
e4c0: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
e4d0: 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
e4e0: 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61  everts to the la
e4f0: 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65  st value inserte
e500: 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  d before the tri
e510: 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a  gger fired..**.*
e520: 2a 20 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74  * An INSERT that
e530: 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
e540: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
e550: 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
e560: 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45   successful INSE
e570: 52 54 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  RT and does not 
e580: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
e590: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
e5a0: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54  s.** routine.  T
e5b0: 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
e5c0: 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
e5d0: 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
e5e0: 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
e5f0: 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
e600: 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
e610: 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
e620: 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
e630: 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
e640: 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
e650: 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54  ls.  When INSERT
e660: 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
e670: 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
e680: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
e690: 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
e6a0: 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
e6b0: 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
e6c0: 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
e6d0: 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
e6e0: 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
e6f0: 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
e700: 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
e710: 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
e720: 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
e730: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
e740: 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
e750: 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  ce..**.** For th
e760: 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
e770: 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 49  is routine, an I
e780: 4e 53 45 52 54 20 69 73 20 63 6f 6e 73 69 64 65  NSERT is conside
e790: 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
e7a0: 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
e7b0: 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
e7c0: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
e7d0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
e7e0: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 31 7d  :.**.** {H12221}
e7f0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   The [sqlite3_la
e800: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
e810: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
e820: 72 6e 73 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a  rns the rowid.**
e830: 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
e840: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
e850: 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 70  cessful INSERT p
e860: 65 72 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20  erformed on the 
e870: 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
e880: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e890: 63 74 69 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69  ction] and withi
e8a0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69  n the same or hi
e8b0: 67 68 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20  gher level.**   
e8c0: 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63         trigger c
e8d0: 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20  ontext, or zero 
e8e0: 69 66 20 74 68 65 72 65 20 68 61 76 65 20 62 65  if there have be
e8f0: 65 6e 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67  en no qualifying
e900: 20 69 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20   inserts..**.** 
e910: 7b 48 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71  {H12223} The [sq
e920: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
e930: 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74  t_rowid()] funct
e940: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
e950: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 61 6d 65  **          same
e960: 20 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c   value when call
e970: 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
e980: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
e990: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d 6d  .**          imm
e9a0: 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20  ediately before 
e9b0: 61 6e 64 20 61 66 74 65 72 20 61 20 52 4f 4c 4c  and after a ROLL
e9c0: 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  BACK..**.** ASSU
e9d0: 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
e9e0: 41 31 32 32 33 32 7d 20 49 66 20 61 20 73 65 70  A12232} If a sep
e9f0: 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
ea00: 66 6f 72 6d 73 20 61 20 6e 65 77 20 49 4e 53 45  forms a new INSE
ea10: 52 54 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  RT on the same.*
ea20: 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
ea30: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
ea40: 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
ea50: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
ea60: 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  wid()].**       
ea70: 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72     function is r
ea80: 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
ea90: 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
eaa0: 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a   insert rowid,.*
eab0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
eac0: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
ead0: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
eae0: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
eaf0: 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ()] is.**       
eb00: 20 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65     unpredictable
eb10: 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
eb20: 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
eb30: 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
eb40: 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20  *          last 
eb50: 69 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f  insert rowid..*/
eb60: 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
eb70: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
eb80: 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
eb90: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
eba0: 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
ebb0: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
ebc0: 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20  dified {H12240} 
ebd0: 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10600>.**.** T
ebe0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
ebf0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
ec00: 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73  of database rows
ec10: 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67   that were chang
ec20: 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65  ed.** or inserte
ec30: 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20  d or deleted by 
ec40: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
ec50: 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20  y completed SQL 
ec60: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20  statement.** on 
ec70: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
ec80: 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
ec90: 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
eca0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f   parameter..** O
ecb0: 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74  nly changes that
ecc0: 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
ecd0: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 49  ecified by the I
ece0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a  NSERT, UPDATE,.*
ecf0: 2a 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  * or DELETE stat
ed00: 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
ed10: 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
ed20: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
ed30: 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20  ** triggers are 
ed40: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65  not counted. Use
ed50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
ed60: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
ed70: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69  unction.** to fi
ed80: 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
ed90: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
eda0: 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
edb0: 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
edc0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f  ers..**.** A "ro
edd0: 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
ede0: 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
edf0: 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
ee00: 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
ee10: 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
ee20: 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
ee30: 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
ee40: 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
ee50: 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
ee60: 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43  ffects of REPLAC
ee70: 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
ee80: 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
ee90: 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
eea0: 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42  essing, DROP TAB
eeb0: 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  LE, or by any ot
eec0: 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
eed0: 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
eee0: 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
eef0: 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  nges..**.** A "t
ef00: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
ef10: 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
ef20: 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
ef30: 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
ef40: 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
ef50: 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d  of a trigger.  M
ef60: 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
ef70: 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
ef80: 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
ef90: 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
efa0: 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
efb0: 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
efc0: 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
efd0: 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
efe0: 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
eff0: 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
f000: 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
f010: 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
f020: 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
f030: 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
f040: 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
f050: 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
f060: 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
f070: 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
f080: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
f090: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
f0a0: 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
f0b0: 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
f0c0: 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
f0d0: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
f0e0: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
f0f0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
f100: 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
f110: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
f120: 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
f130: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
f140: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
f150: 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
f160: 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
f170: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73  text..**.** Thus
f180: 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  , when called fr
f190: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
f1a0: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
f1b0: 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e  returns the.** n
f1c0: 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
f1d0: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
f1e0: 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
f1f0: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
f200: 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72   that also occur
f210: 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c  red at the top l
f220: 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68  evel.  Within th
f230: 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
f240: 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
f250: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
f260: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
f270: 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
f280: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
f290: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
f2a0: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
f2b0: 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
f2c0: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
f2d0: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
f2e0: 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
f2f0: 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
f300: 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
f310: 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
f320: 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
f330: 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
f340: 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
f350: 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
f360: 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
f370: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51  ontext..**.** SQ
f380: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
f390: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
f3a0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
f3b0: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
f3c0: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
f3d0: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
f3e0: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
f3f0: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66   (This is much f
f400: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
f410: 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20  .** through and 
f420: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
f430: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f  ual elements fro
f440: 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42  m the table.)  B
f450: 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a  ecause of this.*
f460: 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  * optimization, 
f470: 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e  the deletions in
f480: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
f490: 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77  ble" are not row
f4a0: 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20   changes and.** 
f4b0: 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e  will not be coun
f4c0: 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
f4d0: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20  e3_changes() or 
f4e0: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
f4f0: 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e  hanges()].** fun
f500: 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65  ctions, regardle
f510: 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ss of the number
f520: 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61   of elements tha
f530: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c  t were originall
f540: 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c  y.** in the tabl
f550: 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63  e.  To get an ac
f560: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20  curate count of 
f570: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
f580: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a  ws deleted, use.
f590: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
f5a0: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69  table WHERE 1" i
f5b0: 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  nstead..**.** IN
f5c0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
f5d0: 7b 48 31 32 32 34 31 7d 20 54 68 65 20 5b 73 71  {H12241} The [sq
f5e0: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
f5f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
f600: 72 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  return the numbe
f610: 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r of.**         
f620: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
f630: 73 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  sed by the most 
f640: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
f650: 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20  PDATE,.**       
f660: 20 20 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61     or DELETE sta
f670: 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61  tement on the sa
f680: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
f690: 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20  ection and.**   
f6a0: 20 20 20 20 20 20 20 77 69 74 68 69 6e 20 74 68         within th
f6b0: 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72  e same or higher
f6c0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
f6d0: 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65  , or zero if the
f6e0: 72 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20  re have.**      
f6f0: 20 20 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79      not been any
f700: 20 71 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20   qualifying row 
f710: 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  changes..**.** {
f720: 48 31 32 32 34 33 7d 20 53 74 61 74 65 6d 65 6e  H12243} Statemen
f730: 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ts of the form "
f740: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
f750: 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a  ename" with no.*
f760: 2a 20 20 20 20 20 20 20 20 20 20 57 48 45 52 45  *          WHERE
f770: 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 63 61   clause shall ca
f780: 75 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 63  use subsequent c
f790: 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20  alls to.**      
f7a0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 68 61      [sqlite3_cha
f7b0: 6e 67 65 73 28 29 5d 20 74 6f 20 72 65 74 75 72  nges()] to retur
f7c0: 6e 20 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c 65  n zero, regardle
f7d0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ss of the.**    
f7e0: 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
f7f0: 72 6f 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20  rows originally 
f800: 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a  in the table..**
f810: 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
f820: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 35 32 7d 20  .**.** {A12252} 
f830: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
f840: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
f850: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
f860: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f870: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
f880: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
f890: 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
f8a0: 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
f8b0: 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20  ue returned.**  
f8c0: 20 20 20 20 20 20 20 20 69 73 20 75 6e 70 72 65          is unpre
f8d0: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
f8e0: 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
f8f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
f900: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
f910: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f920: 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
f930: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48  Rows Modified {H
f940: 31 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a  12260} <S10600>.
f950: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
f960: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
f970: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
f980: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
f990: 49 4e 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54  INSERT,.** UPDAT
f9a0: 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
f9b0: 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65  ements since the
f9c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f9d0: 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65  ction] was opene
f9e0: 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20  d..** The count 
f9f0: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
fa00: 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72  nges from all tr
fa10: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20  igger contexts. 
fa20: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
fa30: 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
fa40: 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
fa50: 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
fa60: 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  t REPLACE constr
fa70: 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
fa80: 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
fa90: 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44  processing, or D
faa0: 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73  ROP table proces
fab0: 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61  sing..** The cha
fac0: 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
fad0: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
fae0: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
faf0: 61 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20  akes them is.** 
fb00: 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
fb10: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
fb20: 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74  ndle is passed t
fb30: 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
fb40: 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
fb50: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
fb60: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
fb70: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d  plements the com
fb80: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f  mand "DELETE FRO
fb90: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74  M table" without
fba0: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a   a WHERE clause.
fbb0: 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61  ** by dropping a
fbc0: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68  nd recreating th
fbd0: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20  e table.  (This 
fbe0: 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74  is much faster t
fbf0: 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72  han going.** thr
fc00: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e  ough and deletin
fc10: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65  g individual ele
fc20: 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74  ments from the t
fc30: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20  able.)  Because 
fc40: 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d  of this.** optim
fc50: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c  ization, the del
fc60: 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54  etions in "DELET
fc70: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72  E FROM table" ar
fc80: 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65  e not row change
fc90: 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f  s and.** will no
fca0: 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20  t be counted by 
fcb0: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
fcc0: 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65  ges() or [sqlite
fcd0: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
fce0: 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c  )].** functions,
fcf0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
fd00: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
fd10: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
fd20: 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e  originally.** in
fd30: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20   the table.  To 
fd40: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
fd50: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
fd60: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
fd70: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
fd80: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
fd90: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
fda0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
fdb0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
fdc0: 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
fdd0: 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
fde0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  NTS:.**.** {H122
fdf0: 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
fe00: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
fe10: 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  ] returns the to
fe20: 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20  tal number.**   
fe30: 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68         of row ch
fe40: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
fe50: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
fe60: 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  and/or DELETE.**
fe70: 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d            statem
fe80: 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  ents on the same
fe90: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
fea0: 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a  ction], in any.*
feb0: 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67  *          trigg
fec0: 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63  er context, sinc
fed0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
fee0: 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72  onnection was cr
fef0: 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  eated..**.** {H1
ff00: 32 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73  2263} Statements
ff10: 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45   of the form "DE
ff20: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e  LETE FROM tablen
ff30: 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20  ame" with no.** 
ff40: 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63           WHERE c
ff50: 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20  lause shall not 
ff60: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
ff70: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20   returned.**    
ff80: 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
ff90: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
ffa0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  )]..**.** ASSUMP
ffb0: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
ffc0: 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72  2264} If a separ
ffd0: 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
ffe0: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
fff0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
10000 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
10010 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69       while [sqli
10020 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
10030 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
10040 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
10050 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
10060 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
10070 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
10080 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
10090 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
100a0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
100b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
100c0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
100d0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
100e0 20 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30   {H12270} <S3050
100f0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
10100 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
10110 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
10120 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
10130 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
10140 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
10150 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
10160 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
10170 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
10180 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
10190 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
101a0 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
101b0 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
101c0 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
101d0 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
101e0 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
101f0 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
10200 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
10210 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f  ** It is safe to
10220 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
10230 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
10240 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
10250 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
10260 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
10270 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
10280 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
10290 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
102a0 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
102b0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
102c0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
102d0 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
102e0 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
102f0 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
10300 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
10310 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
10320 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70  .** If an SQL op
10330 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
10340 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
10350 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
10360 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
10370 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
10380 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
10390 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
103a0 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
103b0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
103c0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
103d0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
103e0 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65  **.** An SQL ope
103f0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
10400 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
10410 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
10420 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66  NTERRUPT]..** If
10430 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
10440 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
10450 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
10460 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
10470 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
10480 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
10490 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
104a0 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
104b0 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
104c0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
104d0 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
104e0 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
104f0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
10500 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
10510 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
10520 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
10530 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
10540 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
10550 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  turns..**.** INV
10560 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
10570 48 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c  H12271} The [sql
10580 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
10590 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
105a0 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69   force all runni
105b0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ng.**          S
105c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  QL statements as
105d0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
105e0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
105f0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
10600 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61         to halt a
10610 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20  fter processing 
10620 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69  at most one addi
10630 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61  tional row of da
10640 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37  ta..**.** {H1227
10650 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65  2} Any SQL state
10660 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74  ment that is int
10670 65 72 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c  errupted by [sql
10680 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
10690 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
106a0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
106b0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
106c0 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
106d0 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20  .**.** {A12279} 
106e0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
106f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
10700 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
10710 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
10720 20 20 20 20 20 20 20 20 20 20 69 73 20 72 75 6e            is run
10730 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
10740 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
10750 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64   happen..*/.void
10760 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
10770 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
10780 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
10790 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
107a0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
107b0 43 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30  Complete {H10510
107c0 7d 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70200>.**.**
107d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
107e0 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
107f0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
10800 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
10810 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
10820 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
10830 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f  seems to form co
10840 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61  mplete a SQL sta
10850 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
10860 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
10870 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
10880 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
10890 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
108a0 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
108b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
108c0 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68  eturn true if th
108d0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
108e0 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
108f0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
10900 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61  tatement.  A sta
10910 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
10920 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
10930 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
10940 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
10950 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
10960 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a  a fragment of a.
10970 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ** CREATE TRIGGE
10980 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65  R statement.  Se
10990 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
109a0 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
109b0 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
109c0 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
109d0 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
109e0 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
109f0 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
10a00 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
10a10 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
10a20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
10a30 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
10a40 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
10a50 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
10a60 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
10a70 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ator..**.** Thes
10a80 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
10a90 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
10aa0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
10ab0 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
10ac0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
10ad0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
10ae0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
10af0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d  :.**.** {H10511}
10b00 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 65 76   A successful ev
10b10 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  aluation of [sql
10b20 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
10b30 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
10b40 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
10b50 65 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73  e16()] functions
10b60 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20   shall.**       
10b70 20 20 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65     return a nume
10b80 72 69 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c  ric 1 if and onl
10b90 79 20 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f  y if the last no
10ba0 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20  n-whitespace.** 
10bb0 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69           token i
10bc0 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 69 73  n their input is
10bd0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61   a semicolon tha
10be0 74 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77  t is not in betw
10bf0 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  een.**          
10c00 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e  the BEGIN and EN
10c10 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 54 52  D of a CREATE TR
10c20 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
10c30 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20  .**.** {H10512} 
10c40 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
10c50 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
10c60 75 72 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e  urs during an in
10c70 76 6f 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  vocation.**     
10c80 20 20 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33       of [sqlite3
10c90 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20  _complete()] or 
10ca0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
10cb0 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a  e16()] then the.
10cc0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  **          rout
10cd0 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
10ce0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
10cf0 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
10d00 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31  NS:.**.** {A1051
10d10 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  2} The input to 
10d20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
10d30 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
10d40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
10d50 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38  *          UTF-8
10d60 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
10d70 41 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75  A10513} The inpu
10d80 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
10d90 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
10da0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
10db0 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
10dc0 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20    UTF-16 string 
10dd0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
10de0 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
10df0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
10e00 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
10e10 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
10e20 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
10e30 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
10e40 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
10e50 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
10e60 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
10e70 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33  USY Errors {H123
10e80 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a  10} <S40400>.**.
10e90 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
10ea0 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
10eb0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
10ec0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
10ed0 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
10ee0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
10ef0 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
10f00 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
10f10 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
10f20 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
10f30 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ked..**.** If th
10f40 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
10f50 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
10f60 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
10f70 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
10f80 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75  CKED].** is retu
10f90 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
10fa0 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
10fb0 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20  ng the lock. If 
10fc0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
10fd0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
10fe0 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
10ff0 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f  ack will be invo
11000 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
11010 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  uments..**.** Th
11020 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11030 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20   to the handler 
11040 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
11050 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
11060 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
11070 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
11080 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
11090 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65  ndler().  The se
110a0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
110b0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
110c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
110d0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
110e0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
110f0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
11100 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
11110 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
11120 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73  .  If the.** bus
11130 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
11140 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
11150 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
11160 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
11170 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
11180 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
11190 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
111a0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
111b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
111c0 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
111d0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
111e0 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
111f0 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
11200 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
11210 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
11220 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
11230 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
11240 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
11250 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
11260 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
11270 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
11280 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
11290 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
112a0 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20   contention. If 
112b0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
112c0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
112d0 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
112e0 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
112f0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
11300 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
11310 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
11320 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
11330 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
11340 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
11350 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
11360 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
11370 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
11380 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
11390 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
113a0 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
113b0 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
113c0 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
113d0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
113e0 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
113f0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
11400 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
11410 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
11420 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
11430 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
11440 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
11450 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
11460 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
11470 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
11480 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
11490 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
114a0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
114b0 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
114c0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
114d0 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
114e0 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
114f0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
11500 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
11510 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
11520 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
11530 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
11540 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
11550 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
11560 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
11570 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
11580 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
11590 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
115a0 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
115b0 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
115c0 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
115d0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
115e0 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  proceed..**.** T
115f0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
11600 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
11610 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
11620 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
11630 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
11640 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
11650 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
11660 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
11670 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
11680 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
11690 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
116a0 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
116b0 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
116c0 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
116d0 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
116e0 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
116f0 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
11700 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
11710 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
11720 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
11730 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
11740 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
11750 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
11760 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
11770 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
11780 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
11790 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
117a0 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 75  ers.  If it is u
117b0 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
117c0 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
117d0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
117e0 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
117f0 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
11800 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
11810 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
11820 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
11830 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
11840 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
11850 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
11860 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
11870 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
11880 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65  LOCKED].  This e
11890 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
118a0 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
118b0 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
118c0 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
118d0 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
118e0 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
118f0 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
11900 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
11910 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
11920 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
11930 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
11940 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
11950 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
11960 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
11970 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  nt..**.** There 
11980 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
11990 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
119a0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
119b0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
119c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
119d0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
119e0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
119f0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
11a00 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20  y set handler.  
11a10 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
11a20 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
11a30 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
11a40 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
11a50 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
11a60 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
11a70 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
11a80 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
11a90 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
11aa0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
11ab0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11ac0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
11ad0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
11ae0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
11af0 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
11b00 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
11b10 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41  ior..** .** INVA
11b20 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
11b30 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69  12311} The [sqli
11b40 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
11b50 28 44 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f  (D,C,A)] functio
11b60 6e 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a  n shall replace.
11b70 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 73 79  **          busy
11b80 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65   callback in the
11b90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11ba0 63 74 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 20  ction] D with a 
11bb0 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
11bc0 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
11bd0 65 72 20 43 20 61 6e 64 20 61 70 70 6c 69 63 61  er C and applica
11be0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
11bf0 72 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  r A..**.** {H123
11c00 31 32 7d 20 4e 65 77 6c 79 20 63 72 65 61 74 65  12} Newly create
11c10 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  d [database conn
11c20 65 63 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68  ections] shall h
11c30 61 76 65 20 61 20 62 75 73 79 0a 2a 2a 20 20 20  ave a busy.**   
11c40 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 6f         handler o
11c50 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  f NULL..**.** {H
11c60 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20  12314} When two 
11c70 6f 72 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 73  or more [databas
11c80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73  e connections] s
11c90 68 61 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20  hare a.**       
11ca0 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62     [sqlite3_enab
11cb0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20  le_shared_cache 
11cc0 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c  | common cache],
11cd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
11ce0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
11cf0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  r the database c
11d00 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e  onnection curren
11d10 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  tly using.**    
11d20 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65 20        the cache 
11d30 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64  shall be invoked
11d40 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 20   when the cache 
11d50 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63  encounters a loc
11d60 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36  k..**.** {H12316
11d70 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 64  } If a busy hand
11d80 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ler callback ret
11d90 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  urns zero, then 
11da0 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
11db0 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  face.**         
11dc0 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74   that provoked t
11dd0 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  he locking event
11de0 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53   shall return [S
11df0 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
11e00 2a 2a 20 7b 48 31 32 33 31 38 7d 20 53 51 4c 69  ** {H12318} SQLi
11e10 74 65 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73  te shall invokes
11e20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
11e30 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  r with two argum
11e40 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20  ents which.**   
11e50 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f 70         are a cop
11e60 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72  y of the pointer
11e70 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
11e80 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
11e90 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
11ea0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
11eb0 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75  ler()] and a cou
11ec0 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
11ed0 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20   of prior.**    
11ee0 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e        invocation
11ef0 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68 61  s of the busy ha
11f00 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61  ndler for the sa
11f10 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
11f20 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
11f30 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33  ONS:.**.** {A123
11f40 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c  19} A busy handl
11f50 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
11f60 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
11f70 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
11f80 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72        or [prepar
11f90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
11fa0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
11fb0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
11fc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
11fd0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
11fe0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
11ff0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
12000 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
12010 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
12020 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34  t {H12340} <S404
12030 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  10>.**.** This r
12040 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
12050 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
12060 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
12070 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
12080 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
12090 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
120a0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
120b0 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68  s locked.  The h
120c0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
120d0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
120e0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
120f0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
12100 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
12110 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
12120 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41  ated. {H12343} A
12130 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73  fter "ms" millis
12140 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
12150 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
12160 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
12170 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
12180 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
12190 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
121a0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
121b0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
121c0 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74  .**.** Calling t
121d0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
121e0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
121f0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
12200 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
12210 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
12220 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ndlers..**.** Th
12230 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
12240 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
12250 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
12260 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
12270 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12280 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f  any any given mo
12290 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
122a0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
122b0 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
122c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
122d0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
122e0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
122f0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
12300 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
12310 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
12320 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ared..**.** INVA
12330 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
12340 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  12341} The [sqli
12350 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
12360 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61  ()] function sha
12370 6c 6c 20 6f 76 65 72 72 69 64 65 20 61 6e 79 20  ll override any 
12380 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  prior.**        
12390 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f    [sqlite3_busy_
123a0 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73  timeout()] or [s
123b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
123c0 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a  ler()] setting.*
123d0 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68  *          on th
123e0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
123f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
12400 0a 2a 2a 20 7b 48 31 32 33 34 33 7d 20 49 66 20  .** {H12343} If 
12410 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
12420 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75  r to [sqlite3_bu
12430 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73  sy_timeout()] is
12440 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20   less than.**   
12450 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20         or equal 
12460 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  to zero, then th
12470 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73  e busy handler s
12480 68 61 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 20  hall be cleared 
12490 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20  so that.**      
124a0 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65      all subseque
124b0 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  nt locking event
124c0 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65  s immediately re
124d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
124e0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34  Y]..**.** {H1234
124f0 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61  4} If the 2nd pa
12500 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
12510 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
12520 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76  ()] is a positiv
12530 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
12540 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62  mber N, then a b
12550 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c  usy handler shal
12560 6c 20 62 65 20 73 65 74 20 74 68 61 74 20 72 65  l be set that re
12570 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a  peatedly calls.*
12580 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 78  *          the x
12590 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69  Sleep() method i
125a0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  n the [sqlite3_v
125b0 66 73 20 7c 20 56 46 53 20 69 6e 74 65 72 66 61  fs | VFS interfa
125c0 63 65 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20  ce] until.**    
125d0 20 20 20 20 20 20 65 69 74 68 65 72 20 74 68 65        either the
125e0 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20   lock clears or 
125f0 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61  until the cumula
12600 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65 0a  tive sleep time.
12610 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6f  **          repo
12620 72 74 65 64 20 62 61 63 6b 20 62 79 20 78 53 6c  rted back by xSl
12630 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e 20  eep() exceeds N 
12640 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f  milliseconds..*/
12650 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
12660 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
12670 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
12680 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
12690 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
126a0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
126b0 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20  ueries {H12370} 
126c0 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44  <S10000>.**.** D
126d0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
126e0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
126f0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
12700 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
12710 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
12720 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
12730 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
12740 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
12750 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
12760 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
12770 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
12780 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
12790 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
127a0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
127b0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
127c0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
127d0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
127e0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
127f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
12800 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
12810 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
12820 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
12830 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
12840 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
12850 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
12860 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
12870 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
12880 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
12890 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
128a0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
128b0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
128c0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
128d0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
128e0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
128f0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
12900 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
12910 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
12920 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
12930 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
12940 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
12950 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
12960 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
12970 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
12980 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
12990 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
129a0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
129b0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
129c0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
129d0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
129e0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
129f0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
12a00 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
12a10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
12a20 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
12a30 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
12a40 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
12a50 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
12a60 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
12a70 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
12a80 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
12a90 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
12aa0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
12ab0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
12ac0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
12ad0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
12ae0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
12af0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
12b00 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
12b10 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
12b20 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
12b30 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
12b40 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
12b50 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
12b60 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
12b70 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
12b80 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
12b90 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
12ba0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
12bb0 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
12bc0 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
12bd0 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
12be0 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
12bf0 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
12c00 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
12c10 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
12c20 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
12c30 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
12c40 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
12c50 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
12c60 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
12c70 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
12c80 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
12c90 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
12ca0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
12cb0 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
12cc0 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
12cd0 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
12ce0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12cf0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
12d00 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
12d10 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
12d20 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
12d30 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
12d40 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
12d50 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
12d60 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
12d70 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
12d80 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
12d90 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
12da0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
12db0 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
12dc0 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
12dd0 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
12de0 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
12df0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
12e00 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
12e10 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
12e20 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
12e30 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
12e40 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
12e50 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
12e60 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
12e70 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
12e80 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
12e90 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
12ea0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
12eb0 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
12ec0 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20  .  It returns a 
12ed0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
12ee0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
12ef0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
12f00 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
12f10 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69   After the calli
12f20 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20  ng function has 
12f30 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
12f40 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68  he result, it sh
12f50 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65  ould.** pass the
12f60 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
12f70 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
12f80 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
12f90 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
12fa0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
12fb0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
12fc0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
12fd0 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
12fe0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
12ff0 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
13000 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
13010 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
13020 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
13030 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
13040 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
13050 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
13060 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
13070 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
13080 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
13090 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
130a0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
130b0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
130c0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
130d0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
130e0 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
130f0 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
13100 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
13110 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
13120 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
13130 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
13140 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
13150 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
13160 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
13170 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
13180 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
13190 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
131a0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
131b0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
131c0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
131d0 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
131e0 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
131f0 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
13200 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
13210 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
13220 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
13230 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
13240 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
13250 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71  rrcode()] or [sq
13260 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
13270 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
13280 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31  S:.**.** {H12371
13290 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  } If a [sqlite3_
132a0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69  get_table()] fai
132b0 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ls a memory allo
132c0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  cation, then.** 
132d0 20 20 20 20 20 20 20 20 20 69 74 20 73 68 61 6c           it shal
132e0 6c 20 66 72 65 65 20 74 68 65 20 72 65 73 75 6c  l free the resul
132f0 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f  t table under co
13300 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72  nstruction, abor
13310 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
13320 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65    query in proce
13330 73 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 62  ss, skip any sub
13340 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c  sequent queries,
13350 20 73 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20   set the.**     
13360 20 20 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 20       *pazResult 
13370 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74  output pointer t
13380 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72  o NULL and retur
13390 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
133a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d  ..**.** {H12373}
133b0 20 49 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e   If the pnColumn
133c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
133d0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
133e0 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a  ()] is not NULL.
133f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e  **          then
13400 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   a successful in
13410 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
13420 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
13430 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ] shall.**      
13440 20 20 20 20 77 72 69 74 65 20 74 68 65 20 6e 75      write the nu
13450 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
13460 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
13470 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66     result set of
13480 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20   the query into 
13490 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  *pnColumn..**.**
134a0 20 7b 48 31 32 33 37 34 7d 20 49 66 20 74 68 65   {H12374} If the
134b0 20 70 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 72   pnRow parameter
134c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   to [sqlite3_get
134d0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74  _table()] is not
134e0 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
134f0 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 73    then a success
13500 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
13510 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  f [sqlite3_get_t
13520 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a  able()] shall.**
13530 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65 73            writes
13540 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
13550 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  ows in the.**   
13560 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65         result se
13570 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69  t of the query i
13580 6e 74 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a  nto *pnRow..**.*
13590 2a 20 7b 48 31 32 33 37 36 7d 20 41 20 73 75 63  * {H12376} A suc
135a0 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
135b0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67  on of [sqlite3_g
135c0 65 74 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 74  et_table()] that
135d0 20 63 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20   computes.**    
135e0 20 20 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 20        N rows of 
135f0 72 65 73 75 6c 74 20 77 69 74 68 20 43 20 63 6f  result with C co
13600 6c 75 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 68  lumns per row sh
13610 61 6c 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73  all make *pazRes
13620 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ult.**          
13630 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 61  point to an arra
13640 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
13650 20 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 73   (N+1)*C strings
13660 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
13670 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 20 73  .**          C s
13680 74 72 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d  trings are colum
13690 6e 20 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 69  n names as obtai
136a0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  ned from.**     
136b0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
136c0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64  lumn_name()] and
136d0 20 74 68 65 20 72 65 73 74 20 61 72 65 20 63 6f   the rest are co
136e0 6c 75 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c 75  lumn result valu
136f0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  es.**          o
13700 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
13710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
13720 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  t()]..**.** {H12
13730 33 37 39 7d 20 54 68 65 20 76 61 6c 75 65 73 20  379} The values 
13740 69 6e 20 74 68 65 20 70 61 7a 52 65 73 75 6c 74  in the pazResult
13750 20 61 72 72 61 79 20 72 65 74 75 72 6e 65 64 20   array returned 
13760 62 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  by [sqlite3_get_
13770 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20  table()].**     
13780 20 20 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69       shall remai
13790 6e 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c  n valid until cl
137a0 65 61 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eared by [sqlite
137b0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
137c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20  .**.** {H12382} 
137d0 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
137e0 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c  curs during eval
137f0 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  uation of [sqlit
13800 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a  e3_get_table()].
13810 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
13820 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73  function shall s
13830 65 74 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f  et *pazResult to
13840 20 4e 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20   NULL, write an 
13850 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
13860 20 20 20 20 20 20 20 20 20 20 69 6e 74 6f 20 6d            into m
13870 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
13880 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
13890 6c 6f 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20  loc()], make.** 
138a0 20 20 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 72           **pzErr
138b0 6d 73 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61  msg point to tha
138c0 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c  t error message,
138d0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a   and return a.**
138e0 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70            approp
138f0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
13900 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
13910 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
13920 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
13930 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
13940 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
13950 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
13960 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
13970 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
13980 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
13990 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
139a0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
139b0 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
139c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
139d0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
139e0 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
139f0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
13a00 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
13a10 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
13a20 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
13a30 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
13a40 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
13a50 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
13a60 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
13a70 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
13a80 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
13a90 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
13aa0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
13ab0 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
13ac0 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37  g Functions {H17
13ad0 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32  400} <S70000><S2
13ae0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0000>.**.** Thes
13af0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
13b00 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  orkalikes of the
13b10 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
13b20 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
13b30 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
13b40 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
13b50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
13b60 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
13b70 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
13b80 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
13b90 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
13ba0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
13bb0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
13bc0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
13bd0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
13be0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
13bf0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
13c00 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
13c10 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
13c20 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20  _free()].  Both 
13c30 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
13c40 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
13c50 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
13c60 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
13c70 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
13c80 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
13c90 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
13ca0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
13cb0 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e  ** In sqlite3_sn
13cc0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
13cd0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
13ce0 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
13cf0 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
13d00 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
13d10 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
13d20 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
13d30 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
13d40 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
13d50 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
13d60 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
13d70 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
13d80 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
13d90 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
13da0 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
13db0 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
13dc0 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
13dd0 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61  tf().  This is a
13de0 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
13df0 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
13e00 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
13e10 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
13e20 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
13e30 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65  atibility.  Note
13e40 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
13e50 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
13e60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
13e70 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
13e80 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
13e90 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
13ea0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
13eb0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
13ec0 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64  e buffer.  We ad
13ed0 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
13ee0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
13ef0 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
13f00 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
13f10 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
13f20 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
13f30 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
13f40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
13f50 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
13f60 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
13f70 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
13f80 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41  ibility..**.** A
13f90 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
13fa0 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
13fb0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
13fc0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
13fd0 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
13fe0 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
13ff0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
14000 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65  terminated.  The
14010 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
14020 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
14030 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
14040 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
14050 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
14060 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
14070 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
14080 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
14090 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
140a0 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
140b0 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
140c0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ters..**.** Thes
140d0 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
140e0 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
140f0 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
14100 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
14110 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
14120 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
14130 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
14140 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
14150 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
14160 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
14170 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
14180 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
14190 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
141a0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
141b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20  s..**.** The %q 
141c0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
141d0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
141e0 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
141f0 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ll-terminated.**
14200 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
14210 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
14220 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
14230 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
14240 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
14250 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
14260 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
14270 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42  ring literal.  B
14280 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
14290 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
142a0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
142b0 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
142c0 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
142d0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
142e0 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
142f0 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
14300 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
14310 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
14320 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
14330 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
14340 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
14350 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
14360 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
14370 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
14380 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
14390 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
143a0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
143b0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
143c0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
143d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
143e0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
143f0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
14400 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
14410 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
14420 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
14430 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
14440 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
14450 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
14460 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
14470 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
14480 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
14490 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
144a0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
144b0 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
144c0 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
144d0 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
144e0 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
144f0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
14500 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
14510 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
14520 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
14530 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
14540 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
14550 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
14560 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
14570 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
14580 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
14590 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
145a0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
145b0 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
145c0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
145d0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
145e0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
145f0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
14600 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
14610 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
14620 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
14630 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
14640 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
14650 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
14660 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
14670 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
14680 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
14690 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
146a0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
146b0 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
146c0 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  teral..**.** The
146d0 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %Q option works
146e0 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20   like %q except 
146f0 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e  it also adds sin
14700 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e  gle quotes aroun
14710 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65  d.** the outside
14720 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74   of the total st
14730 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61  ring.  Additiona
14740 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61  lly, if the para
14750 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20  meter in the.** 
14760 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73  argument list is
14770 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
14780 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20   %Q substitutes 
14790 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20  the text "NULL" 
147a0 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67  (without.** sing
147b0 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c  le quotes) in pl
147c0 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70  ace of the %Q op
147d0 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65  tion.  So, for e
147e0 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
147f0 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
14800 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
14810 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
14820 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
14830 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
14840 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
14850 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
14860 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
14870 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
14880 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
14890 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
148a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
148b0 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
148c0 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
148d0 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
148e0 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
148f0 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
14900 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
14910 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
14920 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
14930 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74   The "%z" format
14940 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
14950 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22  s exactly like "
14960 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  %s" with the.** 
14970 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
14980 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
14990 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
149a0 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
149b0 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
149c0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
149d0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
149e0 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44  put string. {END
149f0 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  }.**.** INVARIAN
14a00 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30  TS:.**.** {H1740
14a10 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  3}  The [sqlite3
14a20 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20  _mprintf()] and 
14a30 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  [sqlite3_vmprint
14a40 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a  f()] interfaces.
14a50 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74  **           ret
14a60 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74  urn either point
14a70 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
14a80 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
14a90 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20  ings held in.** 
14aa0 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79            memory
14ab0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
14ac0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14ad0 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ] or NULL pointe
14ae0 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  rs if.**        
14af0 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71     a call to [sq
14b00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
14b10 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fails..**.** {H1
14b20 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69  7406}  The [sqli
14b30 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
14b40 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73  interface writes
14b50 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
14b60 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ed.**           
14b70 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74  UTF-8 string int
14b80 6f 20 74 68 65 20 62 75 66 66 65 72 20 70 6f 69  o the buffer poi
14b90 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 73  nted to by the s
14ba0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
14bb0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70 72 6f  **           pro
14bc0 76 69 64 65 64 20 74 68 61 74 20 74 68 65 20 66  vided that the f
14bd0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
14be0 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
14bf0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34  ero..**.** {H174
14c00 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  07}  The [sqlite
14c10 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e  3_snprintf()] in
14c20 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
14c30 20 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a   write slots of.
14c40 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 73  **           its
14c50 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 28   output buffer (
14c60 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
14c70 65 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 68  eter) outside th
14c80 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20  e range.**      
14c90 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67       of 0 throug
14ca0 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69  h N-1 (where N i
14cb0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
14cc0 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20  meter).**       
14cd0 20 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f      regardless o
14ce0 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  f the length of 
14cf0 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20  the string.**   
14d00 20 20 20 20 20 20 20 20 72 65 71 75 65 73 74 65          requeste
14d10 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20  d by the format 
14d20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a  specification..*
14d30 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
14d40 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
14d50 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
14d60 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
14d70 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
14d80 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
14d90 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
14da0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
14db0 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  har*, ...);../*.
14dc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
14dd0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
14de0 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30  ubsystem {H17300
14df0 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
14e00 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
14e10 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72    uses these thr
14e20 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
14e30 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
14e40 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
14e50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
14e60 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
14e70 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
14e80 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
14e90 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
14ea0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
14eb0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
14ec0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
14ed0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
14ee0 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
14ef0 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
14f00 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
14f10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
14f20 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
14f30 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
14f40 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
14f50 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
14f60 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
14f70 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
14f80 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
14f90 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
14fa0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
14fb0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
14fc0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
14fd0 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
14fe0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
14ff0 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d  r.  If the param
15000 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
15010 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
15020 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
15030 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
15040 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
15050 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
15060 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67  r..**.** Calling
15070 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
15080 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
15090 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
150a0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
150b0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
150c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
150d0 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
150e0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
150f0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
15100 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
15110 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
15120 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
15130 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
15140 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
15150 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
15160 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
15170 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
15180 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
15190 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
151a0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
151b0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
151c0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
151d0 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
151e0 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
151f0 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
15200 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
15210 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
15220 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
15230 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
15240 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
15250 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
15260 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
15270 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
15280 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
15290 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
152a0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
152b0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
152c0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
152d0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
152e0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
152f0 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  free()..**.** Th
15300 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
15310 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
15320 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
15330 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
15340 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
15350 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
15360 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
15370 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
15380 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
15390 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
153a0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
153b0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
153c0 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68  arameter.  If th
153d0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
153e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
153f0 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e  lloc().** is a N
15400 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
15410 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
15420 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
15430 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
15440 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65  _malloc(N) where
15450 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
15460 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
15470 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
15480 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e  .** If the secon
15490 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
154a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
154b0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
154c0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
154d0 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
154e0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
154f0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
15500 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
15510 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
15520 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
15530 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
15540 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
15550 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20  loc() returns a 
15560 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
15570 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
15580 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
15590 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
155a0 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69   NULL if suffici
155b0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e  ent memory is un
155c0 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66  available..** If
155d0 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
155e0 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
155f0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
15600 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
15610 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
15620 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
15630 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
15640 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
15650 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
15660 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
15670 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
15680 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
15690 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  d..** If sqlite3
156a0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
156b0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
156c0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
156d0 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
156e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65  ed..**.** The me
156f0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
15700 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
15710 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
15720 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
15730 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
15740 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
15750 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e  te boundary. {EN
15760 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  D}.**.** The def
15770 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ault implementat
15780 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72  ion of the memor
15790 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
157a0 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74  system uses.** t
157b0 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  he malloc(), rea
157c0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
157d0 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  ) provided by th
157e0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
157f0 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32  rary..** {H17382
15800 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51  } However, if SQ
15810 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15820 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
15830 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d  ITE_MEMORY_SIZE=
15840 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65  <i>NNN</i> C pre
15850 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
15860 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69  (where <i>NNN</i
15870 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67  >.** is an integ
15880 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  er), then SQLite
15890 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69 63   create a static
158a0 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61   array of at lea
158b0 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  st.** <i>NNN</i>
158c0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
158d0 6e 64 20 75 73 65 73 20 74 68 61 74 20 61 72 72  nd uses that arr
158e0 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ay for all of it
158f0 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d  s dynamic.** mem
15900 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
15910 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64  eeds. {END}  Add
15920 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  itional memory a
15930 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73  llocator options
15940 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64  .** may be added
15950 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
15960 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  ses..**.** In SQ
15970 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
15980 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
15990 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
159a0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
159b0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
159c0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
159d0 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
159e0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
159f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
15a00 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
15a10 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
15a20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
15a30 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
15a40 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
15a50 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
15a60 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
15a70 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
15a80 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
15a90 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
15aa0 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ls.** the system
15ab0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
15ac0 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
15ad0 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
15ae0 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
15af0 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
15b00 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
15b10 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
15b20 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
15b30 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
15b40 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
15b50 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
15b60 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
15b70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
15b80 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ors are detected
15b90 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72  , but.** they ar
15ba0 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
15bb0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
15bc0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
15bd0 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
15be0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
15bf0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  MEM]..**.** INVA
15c00 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
15c10 31 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71 6c  17303}  The [sql
15c20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20  ite3_malloc(N)] 
15c30 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
15c40 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74  s either a point
15c50 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
15c60 20 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63 6b     a newly check
15c70 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 20  ed-out block of 
15c80 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
15c90 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20   of memory.**   
15ca0 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20          that is 
15cb0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20  8-byte aligned, 
15cc0 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  or it returns NU
15cd0 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 62  LL if it is unab
15ce0 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  le.**           
15cf0 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20 72  to fulfill the r
15d00 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  equest..**.** {H
15d10 31 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71 6c  17304}  The [sql
15d20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20  ite3_malloc(N)] 
15d30 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
15d40 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
15d50 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
15d60 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
15d70 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
15d80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 35 7d  ..**.** {H17305}
15d90 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66    The [sqlite3_f
15da0 72 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63  ree(P)] interfac
15db0 65 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72  e releases memor
15dc0 79 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  y previously.** 
15dd0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
15de0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
15df0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
15e00 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
15e10 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ],.**           
15e20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c 61  making it availa
15e30 62 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a  ble for reuse..*
15e40 2a 0a 2a 2a 20 7b 48 31 37 33 30 36 7d 20 20 41  *.** {H17306}  A
15e50 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
15e60 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73  3_free(NULL)] is
15e70 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
15e80 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 30  p..**.** {H17310
15e90 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  }  A call to [sq
15ea0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c  lite3_realloc(0,
15eb0 4e 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e  N)] is equivalen
15ec0 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20  t to a call.**  
15ed0 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c           to [sql
15ee0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e  ite3_malloc(N)].
15ef0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 32 7d 20  .**.** {H17312} 
15f00 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   A call to [sqli
15f10 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29  te3_realloc(P,0)
15f20 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  ] is equivalent 
15f30 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20  to a call.**    
15f40 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74         to [sqlit
15f50 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a  e3_free(P)]..**.
15f60 2a 2a 20 7b 48 31 37 33 31 35 7d 20 20 54 68 65  ** {H17315}  The
15f70 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
15f80 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  s [sqlite3_mallo
15f90 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72  c()], [sqlite3_r
15fa0 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20  ealloc()],.**   
15fb0 20 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71 6c          and [sql
15fc0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72  ite3_free()] for
15fd0 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f   all of its memo
15fe0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e  ry allocation an
15ff0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 64  d.**           d
16000 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64  eallocation need
16010 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 38  s..**.** {H17318
16020 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
16030 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e  realloc(P,N)] in
16040 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
16050 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72  either a pointer
16060 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f  .**           to
16070 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63   a block of chec
16080 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f  ked-out memory o
16090 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
160a0 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20  es in size.**   
160b0 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20          that is 
160c0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20  8-byte aligned, 
160d0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
160e0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 31  r..**.** {H17321
160f0 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
16100 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
16110 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c  eturns a non-NUL
16120 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69  L pointer, it fi
16130 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rst.**          
16140 20 63 6f 70 69 65 73 20 74 68 65 20 66 69 72 73   copies the firs
16150 74 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f 6e  t K bytes of con
16160 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f  tent from P into
16170 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20 20   the newly.**   
16180 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65          allocate
16190 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20 4b  d block, where K
161a0 20 69 73 20 74 68 65 20 6c 65 73 73 65 72 20 6f   is the lesser o
161b0 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a 65  f N and the size
161c0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
161d0 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a   the buffer P..*
161e0 2a 0a 2a 2a 20 7b 48 31 37 33 32 32 7d 20 20 57  *.** {H17322}  W
161f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  hen [sqlite3_rea
16200 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72  lloc(P,N)] retur
16210 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  ns a non-NULL po
16220 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a  inter, it first.
16230 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 6c  **           rel
16240 65 61 73 65 73 20 74 68 65 20 62 75 66 66 65 72  eases the buffer
16250 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32   P..**.** {H1732
16260 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  3}  When [sqlite
16270 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20  3_realloc(P,N)] 
16280 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
16290 65 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a 2a  e buffer P is.**
162a0 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 6d             not m
162b0 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65 61  odified or relea
162c0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  sed..**.** ASSUM
162d0 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
162e0 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69 6e  17350}  The poin
162f0 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
16300 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
16310 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
16320 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20  ealloc()].**    
16330 20 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 65         must be e
16340 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
16350 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
16360 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
16370 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69  r.**           i
16380 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
16390 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
163a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
163b0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
163c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f  .**           no
163d0 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
163e0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33  sed..**.** {A173
163f0 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61  51}  The applica
16400 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
16410 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
16420 70 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20  part of.**      
16430 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20       a block of 
16440 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
16450 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
16460 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
16470 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 72       [sqlite3_fr
16480 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
16490 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
164a0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
164b0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
164c0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
164d0 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
164e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
164f0 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
16500 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
16510 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
16520 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20 3c  stics {H17370} <
16530 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51  S30210>.**.** SQ
16540 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
16550 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
16560 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
16570 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
16580 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
16590 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
165a0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
165b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
165c0 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
165d0 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
165e0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
165f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
16600 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49  bsystem..**.** I
16610 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
16620 20 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b 73   {H17371} The [s
16630 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
16640 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
16650 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
16660 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20 20   of bytes.**    
16670 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79 20        of memory 
16680 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
16690 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
166a0 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
166b0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20 54  **.** {H17373} T
166c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
166d0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
166e0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
166f0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20  the maximum.**  
16700 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
16710 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16720 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
16730 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
16740 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  rk.**          w
16750 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a  as last reset..*
16760 2a 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54 68  *.** {H17374} Th
16770 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
16780 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
16790 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
167a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
167b0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
167c0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
167d0 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
167e0 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65 64  *          added
167f0 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
16800 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
16810 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
16820 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
16830 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72      but not over
16840 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
16850 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
16860 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
16870 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  **          rout
16880 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
16890 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
168a0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   call..**.** {H1
168b0 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79  7375} The memory
168c0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
168d0 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
168e0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
168f0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
16900 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
16910 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c  ed()] if and onl
16920 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  y if the paramet
16930 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
16940 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72    [sqlite3_memor
16950 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
16960 73 20 74 72 75 65 2e 20 20 54 68 65 20 76 61 6c  s true.  The val
16970 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20  ue returned.**  
16980 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69          by [sqli
16990 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
169a0 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
169b0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
169c0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 6f  **          prio
169d0 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
169e0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
169f0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
16a00 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
16a10 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
16a20 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
16a30 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
16a40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16a50 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
16a60 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
16a70 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30  or {H17390} <S20
16a80 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  000>.**.** SQLit
16a90 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
16aa0 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
16ab0 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
16ac0 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
16ad0 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
16ae0 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20  t random ROWIDs 
16af0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
16b00 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
16b10 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
16b20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
16b30 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
16b40 65 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 52  e ROWID.  The PR
16b50 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  NG is also used 
16b60 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64  for.** the build
16b70 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64  -in random() and
16b80 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51   randomblob() SQ
16b90 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68  L functions.  Th
16ba0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
16bb0 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ows.** applicati
16bc0 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  ons to access th
16bd0 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20  e same PRNG for 
16be0 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a  other purposes..
16bf0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
16c00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
16c10 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
16c20 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
16c30 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54  uffer P..**.** T
16c40 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
16c50 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e  is routine is in
16c60 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e  voked (either in
16c70 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a  ternally or by.*
16c80 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
16c90 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73  n) the PRNG is s
16ca0 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
16cb0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a  omness obtained.
16cc0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e  ** from the xRan
16cd0 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f  domness method o
16ce0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
16cf0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
16d00 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75  ct..** On all su
16d10 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
16d20 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
16d30 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
16d40 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
16d50 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
16d60 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
16d70 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
16d80 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
16d90 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  method..**.** IN
16da0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
16db0 7b 48 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71  {H17392} The [sq
16dc0 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
16dd0 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  (N,P)] interface
16de0 20 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20   writes N bytes 
16df0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  of.**          h
16e00 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
16e10 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  do-randomness in
16e20 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a  to buffer P..*/.
16e30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
16e40 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
16e50 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
16e60 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
16e70 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
16e80 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b  tion Callbacks {
16e90 48 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 3e  H12500} <S70100>
16ea0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
16eb0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ine registers a 
16ec0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16ed0 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
16ee0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
16ef0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
16f00 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
16f10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
16f20 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
16f30 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
16f40 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
16f50 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e  tements are bein
16f60 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79  g compiled.** by
16f70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16f80 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
16f90 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  ants [sqlite3_pr
16fa0 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20  epare_v2()],.** 
16fb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16fc0 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  16()] and [sqlit
16fd0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
16fe0 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a  )].  At various.
16ff0 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
17000 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
17010 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
17020 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
17030 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
17040 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
17050 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
17060 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
17070 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
17080 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
17090 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54   are allowed.  T
170a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
170b0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
170c0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
170d0 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
170e0 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
170f0 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
17100 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
17110 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
17120 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
17130 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
17140 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
17150 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
17160 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
17170 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
17180 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
17190 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
171a0 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74   an error.  If t
171b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
171c0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
171d0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
171e0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
171f0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
17200 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
17210 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
17220 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
17230 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
17240 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
17250 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
17260 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
17270 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
17280 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
17290 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
172a0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
172b0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
172c0 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
172d0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
172e0 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68   is ok.  When th
172f0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
17300 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
17310 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
17320 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
17330 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
17340 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
17350 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
17360 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
17370 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
17380 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
17390 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
173a0 20 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65   denied.  If the
173b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
173c0 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
173d0 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
173e0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
173f0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
17400 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
17410 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
17420 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
17430 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
17440 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
17450 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
17460 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
17470 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
17480 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
17490 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
174a0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
174b0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
174c0 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
174d0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
174e0 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
174f0 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
17500 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
17510 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
17520 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  e..**.** The fir
17530 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
17540 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17550 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
17560 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
17570 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
17580 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
17590 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
175a0 72 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e  rface. The secon
175b0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
175c0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
175d0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
175e0 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
175f0 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
17600 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
17610 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
17620 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
17630 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72  d. The third thr
17640 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
17650 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
17660 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
17670 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
17680 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
17690 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
176a0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
176b0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
176c0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
176d0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
176e0 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
176f0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
17700 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
17710 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
17720 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
17730 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
17740 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
17750 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
17760 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
17770 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
17780 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
17790 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
177a0 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
177b0 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
177c0 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
177d0 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
177e0 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
177f0 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
17800 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
17810 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
17820 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
17830 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
17840 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
17850 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
17860 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
17870 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
17880 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
17890 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
178a0 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
178b0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
178c0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
178d0 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
178e0 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
178f0 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
17900 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
17910 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
17920 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
17930 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
17940 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
17950 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
17960 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
17970 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
17980 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
17990 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
179a0 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
179b0 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
179c0 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
179d0 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
179e0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
179f0 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
17a00 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
17a10 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
17a20 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
17a30 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
17a40 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
17a50 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
17a60 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61   Only a single a
17a70 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
17a80 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
17a90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17aa0 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
17ab0 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
17ac0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17ad0 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
17ae0 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
17af0 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74  call.  Disable t
17b00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
17b10 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
17b20 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
17b30 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
17b40 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
17b50 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
17b60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17b70 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
17b80 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
17b90 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
17ba0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
17bb0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
17bc0 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
17bd0 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
17be0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
17bf0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
17c00 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
17c10 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
17c20 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
17c30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
17c40 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
17c50 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
17c60 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
17c70 0a 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  .** When [sqlite
17c80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
17c90 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
17ca0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
17cb0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
17cc0 20 6d 69 67 68 74 20 62 65 20 72 65 70 72 65 70   might be reprep
17cd0 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
17ce0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
17cf0 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
17d00 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
17d10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
17d20 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
17d30 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
17d40 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
17d50 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
17d60 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
17d70 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
17d80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ()]..**.** Note 
17d90 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
17da0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
17db0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
17dc0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
17dd0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
17de0 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
17df0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
17e00 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
17e10 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
17e20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
17e30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
17e40 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
17e50 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d  :.**.** {H12501}
17e60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
17e70 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e  t_authorizer(D,.
17e80 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ..)] interface r
17e90 65 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20  egisters a.**   
17ea0 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65         authorize
17eb0 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
17ec0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17ed0 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ion D..**.** {H1
17ee0 32 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72  2502} The author
17ef0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
17f00 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
17f10 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
17f20 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67  *          being
17f30 20 70 61 72 73 65 65 64 20 61 6e 64 20 63 6f 6d   parseed and com
17f40 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  piled..**.** {H1
17f50 32 35 30 33 7d 20 49 66 20 74 68 65 20 61 75 74  2503} If the aut
17f60 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17f70 20 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61 6c   returns any val
17f80 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a  ue other than.**
17f90 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
17fa0 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49  E_IGNORE], [SQLI
17fb0 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49  TE_OK], or [SQLI
17fc0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a  TE_DENY], then.*
17fd0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
17fe0 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65 72  pplication inter
17ff0 66 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20 63  face call that c
18000 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  aused.**        
18010 20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72    the authorizer
18020 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e   callback to run
18030 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68   shall fail with
18040 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
18050 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65  [SQLITE_ERROR] e
18060 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e  rror code and an
18070 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
18080 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
18090 2a 20 7b 48 31 32 35 30 34 7d 20 57 68 65 6e 20  * {H12504} When 
180a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
180b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
180c0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
180d0 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20   operation.**   
180e0 20 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64         described
180f0 20 69 73 20 70 72 6f 63 65 73 73 65 64 20 6e 6f   is processed no
18100 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rmally..**.** {H
18110 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20  12505} When the 
18120 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18130 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
18140 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
18150 2a 20 20 20 20 20 20 20 20 20 20 61 70 70 6c 69  *          appli
18160 63 61 74 69 6f 6e 20 69 6e 74 65 72 66 61 63 65  cation interface
18170 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65   call that cause
18180 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  d the.**        
18190 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c    authorizer cal
181a0 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61  lback to run sha
181b0 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20  ll fail.**      
181c0 20 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c      with an [SQL
181d0 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72  ITE_ERROR] error
181e0 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72   code and an err
181f0 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20  or message.**   
18200 20 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e         explainin
18210 67 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73  g that access is
18220 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b   denied..**.** {
18230 48 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61  H12506} If the a
18240 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28  uthorizer code (
18250 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
18260 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
18270 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zer.**          
18280 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51  callback) is [SQ
18290 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74  LITE_READ] and t
182a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
182b0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
182c0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
182d0 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e  TE_IGNORE], then
182e0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
182f0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
18300 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20  ructed to.**    
18310 20 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e        insert a N
18320 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
18330 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
18340 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
18350 64 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20  d have.**       
18360 20 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20     been read if 
18370 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
18380 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a  been returned..*
18390 2a 0a 2a 2a 20 7b 48 31 32 35 30 37 7d 20 49 66  *.** {H12507} If
183a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
183b0 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61  code (the 2nd pa
183c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
183d0 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20  uthorizer.**    
183e0 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20        callback) 
183f0 69 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65  is anything othe
18400 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
18410 45 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  EAD], then.**   
18420 20 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20         a return 
18430 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  of [SQLITE_IGNOR
18440 45 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20  E] has the same 
18450 65 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54  effect as [SQLIT
18460 45 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_DENY]..**.** {
18470 48 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73  H12510} The firs
18480 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
18490 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
184a0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
184b0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
184c0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
184d0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
184e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
184f0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  er()] interface.
18500 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 31 7d 20  .**.** {H12511} 
18510 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18520 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
18530 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
18540 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  er.**          [
18550 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
18560 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
18570 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61  specifies the pa
18580 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a  rticular action.
18590 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62  **          to b
185a0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
185b0 0a 2a 2a 20 7b 48 31 32 35 31 32 7d 20 54 68 65  .** {H12512} The
185c0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
185d0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  ixth parameters 
185e0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
185f0 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  are.**          
18600 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
18610 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
18620 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tain.**         
18630 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61   additional deta
18640 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
18650 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
18660 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  rized..**.** {H1
18670 32 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20  2520} Each call 
18680 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  to [sqlite3_set_
18690 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76  authorizer()] ov
186a0 65 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20 20  errides.**      
186b0 20 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73      any previous
186c0 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74  ly installed aut
186d0 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  horizer..**.** {
186e0 48 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61  H12521} A NULL a
186f0 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20  uthorizer means 
18700 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a  that no authoriz
18710 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ation.**        
18720 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e    callback is in
18730 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  voked..**.** {H1
18740 32 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c  2522} The defaul
18750 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  t authorizer is 
18760 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
18770 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
18780 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
18790 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
187a0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
187b0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
187c0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
187d0 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
187e0 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
187f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18800 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
18810 75 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39  urn Codes {H1259
18820 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a  0} <H12500>.**.*
18830 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
18840 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
18850 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18860 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
18870 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
18880 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
18890 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
188a0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
188b0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
188c0 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
188d0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
188e0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
188f0 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
18900 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
18910 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
18920 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
18930 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
18940 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
18950 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
18960 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
18970 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
18980 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
18990 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
189a0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
189b0 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
189c0 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
189d0 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
189e0 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
189f0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
18a00 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
18a10 64 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31  des {H12550} <H1
18a20 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2500>.**.** The 
18a30 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
18a40 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
18a50 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
18a60 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18a70 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
18a80 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
18a90 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
18aa0 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
18ab0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
18ac0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
18ad0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
18ae0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
18af0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
18b00 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
18b10 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
18b20 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
18b30 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
18b40 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
18b50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18b60 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
18b70 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
18b80 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
18b90 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
18ba0 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
18bb0 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
18bc0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
18bd0 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
18be0 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
18bf0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
18c00 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
18c10 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
18c20 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
18c30 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
18c40 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
18c50 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
18c60 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
18c70 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65    The 5th parame
18c80 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
18c90 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18ca0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
18cb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
18cc0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
18cd0 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
18ce0 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20  cable.  The 6th 
18cf0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
18d00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18d10 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
18d20 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
18d30 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
18d40 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
18d50 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
18d60 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
18d70 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
18d80 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
18d90 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
18da0 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
18db0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a   SQL code..**.**
18dc0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
18dd0 2a 2a 20 7b 48 31 32 35 35 31 7d 20 54 68 65 20  ** {H12551} The 
18de0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18df0 20 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20   to an.**       
18e00 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
18e10 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
18e20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18e30 5d 20 73 68 61 6c 6c 20 62 65 20 61 6e 20 69 6e  ] shall be an in
18e40 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
18e50 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c    [SQLITE_COPY |
18e60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
18e70 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
18e80 20 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20   what action.** 
18e90 20 20 20 20 20 20 20 20 20 69 73 20 62 65 69 6e           is bein
18ea0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  g authorized..**
18eb0 0a 2a 2a 20 7b 48 31 32 35 35 32 7d 20 54 68 65  .** {H12552} The
18ec0 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
18ed0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 0a 2a  ameters to the.*
18ee0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
18ef0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
18f00 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69  er | authorizati
18f10 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20  on callback].** 
18f20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 62           shall b
18f30 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
18f40 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
18f50 6e 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20  n which.**      
18f60 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59      [SQLITE_COPY
18f70 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f   | authorizer co
18f80 64 65 5d 20 69 73 20 75 73 65 64 20 61 73 20 74  de] is used as t
18f90 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18fa0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  ter..**.** {H125
18fb0 35 33 7d 20 54 68 65 20 35 74 68 20 70 61 72 61  53} The 5th para
18fc0 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
18fd0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
18fe0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
18ff0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
19000 6c 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65  llback] shall be
19010 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20   the name.**    
19020 20 20 20 20 20 20 6f 66 20 74 68 65 20 64 61 74        of the dat
19030 61 62 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20  abase (example: 
19040 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20  "main", "temp", 
19050 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
19060 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  ble..**.** {H125
19070 35 34 7d 20 54 68 65 20 36 74 68 20 70 61 72 61  54} The 6th para
19080 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
19090 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
190a0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
190b0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
190c0 6c 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65  llback] shall be
190d0 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20   the name.**    
190e0 20 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e        of the inn
190f0 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
19100 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
19110 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
19120 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
19130 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
19140 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
19150 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
19160 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
19170 2a 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c  *          top-l
19180 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
19190 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
191a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
191b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
191c0 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
191d0 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
191e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
191f0 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
19200 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
19210 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
19220 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
19230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19240 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
19250 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
19260 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
19270 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19280 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19290 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
192a0 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
192b0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
192c0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
192d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
192e0 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
192f0 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
19300 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
19310 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19320 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
19330 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
19340 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
19350 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
19360 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
19370 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
19380 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
19390 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
193a0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
193b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
193c0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
193d0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
193e0 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
193f0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
19400 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
19410 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
19420 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
19430 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
19440 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19450 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19460 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
19470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
19480 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19490 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
194a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
194b0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
194c0 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
194d0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
194e0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
194f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19500 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
19510 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
19520 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
19530 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19540 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19550 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
19560 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
19570 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
19580 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
19590 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
195a0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
195b0 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
195c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
195d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
195e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
195f0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
19600 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
19610 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
19620 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19630 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19640 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
19650 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
19660 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
19670 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19690 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
196a0 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
196b0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
196c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
196d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
196e0 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
196f0 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
19700 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
19710 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19720 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
19730 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
19740 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
19750 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
19760 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
19780 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
19790 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
197a0 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
197b0 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
197c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
197d0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
197e0 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
197f0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
19800 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
19810 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
19820 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
19830 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
19840 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
19850 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19860 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
19870 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
19880 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  22   /* NULL    
19890 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
198a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
198b0 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
198c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
198d0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
198e0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
198f0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
19900 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
19910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
19920 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
19930 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19940 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19950 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
19960 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
19970 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
19980 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
19990 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
199a0 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
199b0 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
199c0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
199d0 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
199e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
199f0 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
19a00 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
19a10 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
19a20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19a30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19a40 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
19a50 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
19a60 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
19a70 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19a80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19a90 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
19aa0 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
19ab0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19ac0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
19ad0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19ae0 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
19af0 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
19b00 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19b10 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
19b20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19b30 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
19b40 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46         31   /* F
19b50 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e  unction Name   N
19b60 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19b70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19b80 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
19b90 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
19ba0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
19bb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19bc0 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
19bd0 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
19be0 20 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30   {H12280} <S6040
19bf0 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
19c00 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  AL.**.** These r
19c10 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
19c20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
19c30 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
19c40 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
19c50 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
19c60 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
19c70 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
19c80 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  s..**.** The cal
19c90 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
19ca0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
19cb0 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
19cc0 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
19cd0 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
19ce0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
19cf0 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
19d00 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
19d10 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  )]..** The callb
19d20 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54  ack returns a UT
19d30 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
19d40 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
19d50 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68  nt text.** as th
19d60 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
19d70 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
19d80 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  ng.  Additional 
19d90 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a  callbacks occur.
19da0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
19db0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
19dc0 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
19dd0 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
19de0 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
19df0 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
19e00 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
19e10 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
19e20 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  er..**.** The ca
19e30 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
19e40 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
19e50 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
19e60 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
19e70 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
19e80 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54  ent finishes.  T
19e90 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
19ea0 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
19eb0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
19ec0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
19ed0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
19ee0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
19ef0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
19f00 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
19f10 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  k to run..**.** 
19f20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
19f30 2a 20 7b 48 31 32 32 38 31 7d 20 54 68 65 20 63  * {H12281} The c
19f40 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19f50 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b   registered by [
19f60 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
19f70 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68   .**          sh
19f80 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  all be invoked.*
19f90 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65  *          whene
19fa0 76 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ver an SQL state
19fb0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
19fc0 73 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e 64  s to execute and
19fd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
19fe0 6e 65 76 65 72 20 61 20 74 72 69 67 67 65 72 20  never a trigger 
19ff0 73 75 62 70 72 6f 67 72 61 6d 20 66 69 72 73 74  subprogram first
1a000 20 62 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a   begins to run..
1a010 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 32 7d 20 45  **.** {H12282} E
1a020 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ach call to [sql
1a030 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 73 68  ite3_trace()] sh
1a040 61 6c 6c 20 6f 76 65 72 72 69 64 65 20 74 68 65  all override the
1a050 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20   previously.**  
1a060 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
1a070 65 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ed trace callbac
1a080 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 33  k..**.** {H12283
1a090 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63  } A NULL trace c
1a0a0 61 6c 6c 62 61 63 6b 20 73 68 61 6c 6c 20 64 69  allback shall di
1a0b0 73 61 62 6c 65 20 74 72 61 63 69 6e 67 2e 0a 2a  sable tracing..*
1a0c0 2a 0a 2a 2a 20 7b 48 31 32 32 38 34 7d 20 54 68  *.** {H12284} Th
1a0d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1a0e0 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
1a0f0 6c 6c 62 61 63 6b 20 73 68 61 6c 6c 20 62 65 20  llback shall be 
1a100 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20  a copy of.**    
1a110 20 20 20 20 20 20 74 68 65 20 70 6f 69 6e 74 65        the pointe
1a120 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
1a130 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  3rd argument to 
1a140 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
1a150 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 35  ]..**.** {H12285
1a160 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  } The second arg
1a170 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61  ument to the tra
1a180 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ce callback is a
1a190 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
1a1a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1a1b0 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  -8 string contai
1a1c0 6e 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ning the origina
1a1d0 6c 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20  l text.**       
1a1e0 20 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74     of the SQL st
1a1f0 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61  atement as it wa
1a200 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b 73  s passed into [s
1a210 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1a220 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  2()].**         
1a230 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
1a240 6e 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f  nt, or an SQL co
1a250 6d 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e 67  mment indicating
1a260 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a   the beginning.*
1a270 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 20  *          of a 
1a280 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72  trigger subprogr
1a290 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  am..**.** {H1228
1a2a0 37 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  7} The callback 
1a2b0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1a2c0 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  red by [sqlite3_
1a2d0 70 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69 6e  profile()] is in
1a2e0 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  voked.**        
1a2f0 20 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74    as each SQL st
1a300 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
1a310 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 38 7d  ..**.** {H12288}
1a320 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1a330 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
1a340 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ile callback is 
1a350 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20  a copy of.**    
1a360 20 20 20 20 20 20 74 68 65 20 33 72 64 20 70 61        the 3rd pa
1a370 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1a380 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a  te3_profile()]..
1a390 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 39 7d 20 54  **.** {H12289} T
1a3a0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a3b0 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69  ter to the profi
1a3c0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  le callback is a
1a3d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
1a3e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1a3f0 2d 38 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  -8 string that c
1a400 6f 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d 70  ontains the comp
1a410 6c 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20  lete text of.** 
1a420 20 20 20 20 20 20 20 20 20 74 68 65 20 53 51 4c           the SQL
1a430 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74   statement as it
1a440 20 77 61 73 20 70 72 6f 63 65 73 73 65 64 20 62   was processed b
1a450 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
1a460 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20  re_v2()].**     
1a470 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69       or the equi
1a480 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  valent..**.** {H
1a490 31 32 32 39 30 7d 20 54 68 65 20 74 68 69 72 64  12290} The third
1a4a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1a4b0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1a4c0 63 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74  ck is an estimat
1a4d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  e.**          of
1a4e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e   the number of n
1a4f0 61 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77 61  anoseconds of wa
1a500 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65  ll-clock time re
1a510 71 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20  quired to.**    
1a520 20 20 20 20 20 20 72 75 6e 20 74 68 65 20 53 51        run the SQ
1a530 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d  L statement from
1a540 20 73 74 61 72 74 20 74 6f 20 66 69 6e 69 73 68   start to finish
1a550 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ..*/.SQLITE_EXPE
1a560 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
1a570 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
1a580 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
1a590 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
1a5a0 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
1a5b0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
1a5c0 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
1a5d0 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
1a5e0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
1a5f0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
1a600 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
1a610 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
1a620 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a630 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
1a640 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31  ss Callbacks {H1
1a650 32 39 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2910} <S60400>.*
1a660 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1a670 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63  e configures a c
1a680 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1a690 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65   - the.** progre
1a6a0 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68  ss callback - th
1a6b0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65  at is invoked pe
1a6c0 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
1a6d0 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e  g long.** runnin
1a6e0 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  g calls to [sqli
1a6f0 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
1a700 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
1a710 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  d.** [sqlite3_ge
1a720 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20  t_table()].  An 
1a730 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
1a740 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
1a750 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
1a760 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
1a770 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
1a780 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72  .**.** If the pr
1a790 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1a7a0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1a7b0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
1a7c0 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
1a7d0 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
1a7e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1a7f0 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
1a800 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
1a810 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
1a820 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
1a830 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
1a840 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
1a850 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1a860 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1a870 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1a880 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1a890 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
1a8a0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
1a8b0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1a8c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1a8d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1a8e0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1a8f0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1a900 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1a910 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1a920 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1a930 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1a940 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1a950 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 31 7d 20 54  **.** {H12911} T
1a960 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1a970 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1a980 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  by sqlite3_progr
1a990 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a  ess_handler().**
1a9a0 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76            is inv
1a9b0 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
1a9c0 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
1a9d0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
1a9e0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1a9f0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
1aa00 2a 2a 20 7b 48 31 32 39 31 32 7d 20 54 68 65 20  ** {H12912} The 
1aa10 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1aa20 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  k is invoked onc
1aa30 65 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69  e for every N vi
1aa40 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  rtual.**        
1aa50 20 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65    machine opcode
1aa60 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
1aa70 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1aa80 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  t to.**         
1aa90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
1aaa0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
1aab0 5d 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67 69  ] call that regi
1aac0 73 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  stered.**       
1aad0 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e     the callback.
1aae0 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74    If N is less t
1aaf0 68 61 6e 20 31 2c 20 73 71 6c 69 74 65 33 5f 70  han 1, sqlite3_p
1ab00 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1ab10 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 63  ).**          ac
1ab20 74 73 20 61 73 20 69 66 20 61 20 4e 55 4c 4c 20  ts as if a NULL 
1ab30 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1ab40 20 68 61 64 20 62 65 65 6e 20 73 70 65 63 69 66   had been specif
1ab50 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ied..**.** {H129
1ab60 31 33 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73  13} The progress
1ab70 20 63 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66   callback itself
1ab80 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62   is identified b
1ab90 79 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 20  y the third.**  
1aba0 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74          argument
1abb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67   to sqlite3_prog
1abc0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 2e 0a  ress_handler()..
1abd0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 34 7d 20 54  **.** {H12914} T
1abe0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
1abf0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72  nt to sqlite3_pr
1ac00 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
1ac10 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   is a.**        
1ac20 20 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70    void pointer p
1ac30 61 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f  assed to the pro
1ac40 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a  gress callback.*
1ac50 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
1ac60 69 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74  ion each time it
1ac70 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
1ac80 2a 2a 20 7b 48 31 32 39 31 35 7d 20 49 66 20 61  ** {H12915} If a
1ac90 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1aca0 33 5f 73 74 65 70 28 29 5d 20 72 65 73 75 6c 74  3_step()] result
1acb0 73 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 20  s in fewer than 
1acc0 4e 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 20 20 20  N opcodes.**    
1acd0 20 20 20 20 20 20 62 65 69 6e 67 20 65 78 65 63        being exec
1ace0 75 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 70  uted, then the p
1acf0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1ad00 20 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65   is never invoke
1ad10 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 36  d..**.** {H12916
1ad20 7d 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20  } Every call to 
1ad30 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73  [sqlite3_progres
1ad40 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20  s_handler()].** 
1ad50 20 20 20 20 20 20 20 20 20 6f 76 65 72 77 72 69           overwri
1ad60 74 65 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73  tes any previous
1ad70 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 70 72  ly registered pr
1ad80 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1ad90 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 37 7d 20 49  **.** {H12917} I
1ada0 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  f the progress h
1adb0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
1adc0 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20  is NULL then no 
1add0 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20 20 20  progress.**     
1ade0 20 20 20 20 20 68 61 6e 64 6c 65 72 20 69 73 20       handler is 
1adf0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
1ae00 48 31 32 39 31 38 7d 20 49 66 20 74 68 65 20 70  H12918} If the p
1ae10 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1ae20 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
1ae30 74 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20  t other than 0, 
1ae40 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
1ae50 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1ae60 20 61 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 69   a if [sqlite3_i
1ae70 6e 74 65 72 72 75 70 74 28 29 5d 20 68 61 64 20  nterrupt()] had 
1ae80 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 20  been called..** 
1ae90 20 20 20 20 20 20 20 20 20 3c 53 33 30 35 30 30           <S30500
1aea0 3e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  >.*/.void sqlite
1aeb0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1aec0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
1aed0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
1aee0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1aef0 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
1af00 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
1af10 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32   Connection {H12
1af20 37 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a  700} <S40200>.**
1af30 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1af40 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
1af50 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1af60 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69  whose name is gi
1af70 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69  ven by the.** fi
1af80 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
1af90 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   The filename ar
1afa0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
1afb0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
1afc0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
1afd0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1afe0 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
1aff0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
1b000 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
1b010 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
1b020 5f 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b 64 61  _open16(). A [da
1b030 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b040 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
1b050 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
1b060 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
1b070 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
1b080 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
1b090 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
1b0a0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
1b0b0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
1b0c0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
1b0d0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
1b0e0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
1b0f0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
1b100 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
1b110 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
1b120 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
1b130 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66  3].** object. If
1b140 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1b150 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
1b160 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
1b170 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
1b180 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
1b190 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
1b1a0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
1b1b0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  e] is returned. 
1b1c0 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
1b1d0 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
1b1e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1b1f0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
1b200 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
1b210 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
1b220 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
1b230 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
1b240 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  r..**.** The def
1b250 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
1b260 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
1b270 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
1b280 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1b290 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1b2a0 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  n_v2() is called
1b2b0 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
1b2c0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1b2d0 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74  e order if sqlit
1b2e0 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75  e3_open16() is u
1b2f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
1b300 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
1b310 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
1b320 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
1b330 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
1b340 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
1b350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b360 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
1b370 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
1b380 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
1b390 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
1b3a0 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
1b3b0 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
1b3c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1b3d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1b3e0 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
1b3f0 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
1b400 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
1b410 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
1b420 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
1b430 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
1b440 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
1b450 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
1b460 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b470 6e 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61  n.  The flags pa
1b480 72 61 6d 65 74 65 72 20 63 61 6e 20 74 61 6b 65  rameter can take
1b490 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
1b4a0 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
1b4b0 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
1b4c0 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
1b4d0 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1b4e0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72  OPEN_NOMUTEX] or
1b4f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1b500 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 3a 0a  LLMUTEX] flags:.
1b510 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
1b520 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1b530 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
1b540 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1b550 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
1b560 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
1b570 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1b580 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
1b590 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
1b5a0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1b5b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1b5c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1b5d0 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
1b5e0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1b5f0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1b600 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1b610 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1b620 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
1b630 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
1b640 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
1b650 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
1b660 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
1b670 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
1b680 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
1b690 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
1b6a0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
1b6b0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1b6c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53  dd>.**.** <dt>[S
1b6d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1b6e0 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
1b6f0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
1b700 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1b710 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1b720 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1b730 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
1b740 63 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a  creates it if.**
1b750 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
1b760 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
1b770 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
1b780 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
1b790 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
1b7a0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1b7b0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
1b7c0 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
1b7d0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
1b7e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1b7f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1b800 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
1b810 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
1b820 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20   shown above or 
1b830 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69  one of the combi
1b840 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
1b850 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20  ove combined.** 
1b860 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
1b870 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f  _OPEN_NOMUTEX] o
1b880 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  r [SQLITE_OPEN_F
1b890 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 2c  ULLMUTEX] flags,
1b8a0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
1b8b0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
1b8c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
1b8d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1b8e0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1b8f0 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
1b900 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b910 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
1b920 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
1b930 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
1b940 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
1b950 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
1b960 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
1b970 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1b980 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1b990 6d 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 5b  me.  If the.** [
1b9a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1b9b0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1b9c0 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1b9d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b9e0 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1b9f0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1ba00 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1ba10 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1ba20 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1ba30 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1ba40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1ba50 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  tart-time..**.**
1ba60 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
1ba70 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1ba80 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1ba90 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
1baa0 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
1bab0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
1bac0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
1bad0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
1bae0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
1baf0 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
1bb00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1bb10 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
1bb20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1bb30 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
1bb40 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
1bb50 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
1bb60 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
1bb70 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
1bb80 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
1bb90 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
1bba0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
1bbb0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
1bbc0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
1bbd0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
1bbe0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
1bbf0 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
1bc00 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
1bc10 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
1bc20 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
1bc30 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
1bc40 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
1bc50 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
1bc60 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
1bc70 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1bc80 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
1bc90 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1bca0 20 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20   created.  This 
1bcb0 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
1bcc0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
1bcd0 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
1bce0 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
1bcf0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1bd00 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
1bd10 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
1bd20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1bd30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1bd40 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1bd50 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
1bd60 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
1bd70 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
1bd80 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
1bd90 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
1bda0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1bdb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
1bdc0 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 20 66  d use.  If the f
1bdd0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1bde0 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
1bdf0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
1be00 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1be10 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
1be20 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
1be30 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
1be40 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
1be50 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
1be60 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1be70 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
1be80 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1be90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1bea0 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
1beb0 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
1bec0 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
1bed0 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
1bee0 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
1bef0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
1bf00 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
1bf10 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
1bf20 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
1bf30 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
1bf40 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
1bf50 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
1bf60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
1bf70 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1bf80 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 31 7d 20 54  **.** {H12701} T
1bf90 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1bfa0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1bfb0 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
1bfc0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1bfd0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
1bfe0 65 72 66 61 63 65 73 20 63 72 65 61 74 65 20 61  erfaces create a
1bff0 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
1c000 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c010 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ction] associate
1c020 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  d with.**       
1c030 20 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20     the database 
1c040 66 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68  file given in th
1c050 65 69 72 20 66 69 72 73 74 20 70 61 72 61 6d 65  eir first parame
1c060 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ter..**.** {H127
1c070 30 32 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d 65  02} The filename
1c080 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
1c090 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
1c0a0 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  8.**          fo
1c0b0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  r [sqlite3_open(
1c0c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1c0d0 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61  open_v2()] and a
1c0e0 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20  s UTF-16.**     
1c0f0 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69       in the nati
1c100 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f  ve byte order fo
1c110 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
1c120 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  6()]..**.** {H12
1c130 37 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75  703} A successfu
1c140 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
1c150 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1c160 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1c170 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  6()],.**        
1c180 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70    or [sqlite3_op
1c190 65 6e 5f 76 32 28 29 5d 20 77 72 69 74 65 73 20  en_v2()] writes 
1c1a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
1c1b0 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ew.**          [
1c1c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c1d0 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e  ion] into *ppDb.
1c1e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 34 7d 20  .**.** {H12704} 
1c1f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
1c200 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1c210 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
1c220 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c230 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
1c240 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
1c250 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e  [SQLITE_OK] upon
1c260 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20   success,.**    
1c270 20 20 20 20 20 20 6f 72 20 61 6e 20 61 70 70 72        or an appr
1c280 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
1c290 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e  ode] on failure.
1c2a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 36 7d 20  .**.** {H12706} 
1c2b0 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74  The default text
1c2c0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20   encoding for a 
1c2d0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65  new database cre
1c2e0 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ated using.**   
1c2f0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1c300 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  open()] or [sqli
1c310 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77  te3_open_v2()] w
1c320 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a  ill be UTF-8..**
1c330 0a 2a 2a 20 7b 48 31 32 37 30 37 7d 20 54 68 65  .** {H12707} The
1c340 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e   default text en
1c350 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77  coding for a new
1c360 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65   database create
1c370 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
1c380 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1c390 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62 65 20 55  n16()] will be U
1c3a0 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  TF-16..**.** {H1
1c3b0 32 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  2709} The [sqlit
1c3c0 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e  e3_open(F,D)] in
1c3d0 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76  terface is equiv
1c3e0 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20  alent to.**     
1c3f0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
1c400 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20  en_v2(F,D,G,0)] 
1c410 77 68 65 72 65 20 74 68 65 20 47 20 70 61 72 61  where the G para
1c420 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20  meter is.**     
1c430 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45       [SQLITE_OPE
1c440 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51  N_READWRITE]|[SQ
1c450 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1c460 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 31  ]..**.** {H12711
1c470 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1c480 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1c490 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
1c4a0 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  )] contains the.
1c4b0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
1c4c0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
1c4d0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65  EN_READONLY] the
1c4e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
1c4f0 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20  s opened.**     
1c500 20 20 20 20 20 66 6f 72 20 72 65 61 64 69 6e 67       for reading
1c510 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   only..**.** {H1
1c520 32 37 31 32 7d 20 49 66 20 74 68 65 20 47 20 70  2712} If the G p
1c530 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1c540 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1c550 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20  ,G,V)] contains 
1c560 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1c570 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  bit value [SQLIT
1c580 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1c590 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  ] then the datab
1c5a0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a  ase is opened.**
1c5b0 20 20 20 20 20 20 20 20 20 20 72 65 61 64 69 6e            readin
1c5c0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
1c5d0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f   possible, or fo
1c5e0 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69  r reading only i
1c5f0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
1c600 20 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20    file is write 
1c610 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
1c620 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1c630 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 33  m..**.** {H12713
1c640 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1c650 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1c660 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
1c670 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20  )] omits the.** 
1c680 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
1c690 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
1c6a0 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20  CREATE] and the 
1c6b0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1c6c0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  t.**          pr
1c6d0 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20  eviously exist, 
1c6e0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1c6f0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  rned..**.** {H12
1c700 37 31 34 7d 20 49 66 20 74 68 65 20 47 20 70 61  714} If the G pa
1c710 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1c720 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
1c730 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74  G,V)] contains t
1c740 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
1c750 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
1c760 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e  _OPEN_CREATE] an
1c770 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  d the database d
1c780 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20  oes not.**      
1c790 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65      previously e
1c7a0 78 69 73 74 2c 20 74 68 65 6e 20 61 6e 20 61 74  xist, then an at
1c7b0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
1c7c0 20 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20   create and.**  
1c7d0 20 20 20 20 20 20 20 20 69 6e 69 74 69 61 6c 69          initiali
1c7e0 7a 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ze the database.
1c7f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 37 7d 20  .**.** {H12717} 
1c800 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1c810 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
1c820 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1c830 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1c840 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1c850 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1c860 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79  2()] is ":memory
1c870 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76  :", then an priv
1c880 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ate,.**         
1c890 20 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d   ephemeral, in-m
1c8a0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69  emory database i
1c8b0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1c8c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a  e connection..**
1c8d0 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
1c8e0 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  Is SQLITE_OPEN_C
1c8f0 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45  REATE|SQLITE_OPE
1c900 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75  N_READWRITE requ
1c910 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ired.**         
1c920 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
1c930 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  _v2()?</todo>.**
1c940 0a 2a 2a 20 7b 48 31 32 37 31 39 7d 20 49 66 20  .** {H12719} If 
1c950 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1c960 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79  NULL or an empty
1c970 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
1c980 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20  private,.**     
1c990 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 20 6f       ephemeral o
1c9a0 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
1c9b0 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
1c9c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f  .**          <to
1c9d0 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45  do>Is SQLITE_OPE
1c9e0 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f  N_CREATE|SQLITE_
1c9f0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72  OPEN_READWRITE r
1ca00 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20  equired.**      
1ca10 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f      in sqlite3_o
1ca20 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e  pen_v2()?</todo>
1ca30 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 31 7d 20  .**.** {H12721} 
1ca40 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
1ca50 6e 6e 65 63 74 69 6f 6e 5d 20 63 72 65 61 74 65  nnection] create
1ca60 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d by [sqlite3_op
1ca70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 0a  en_v2(F,D,G,V)].
1ca80 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
1ca90 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
1caa0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 64  3_vfs] object id
1cab0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
1cac0 56 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20  V parameter,.** 
1cad0 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
1cae0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1caf0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 66 20  _vfs] object if 
1cb00 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  V is a NULL poin
1cb10 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ter..**.** {H127
1cb20 32 33 7d 20 54 77 6f 20 5b 64 61 74 61 62 61 73  23} Two [databas
1cb30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77  e connections] w
1cb40 69 6c 6c 20 73 68 61 72 65 20 61 20 63 6f 6d 6d  ill share a comm
1cb50 6f 6e 20 63 61 63 68 65 20 69 66 20 62 6f 74 68  on cache if both
1cb60 20 77 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   were.**        
1cb70 20 20 6f 70 65 6e 65 64 20 77 69 74 68 20 74 68    opened with th
1cb80 65 20 73 61 6d 65 20 56 46 53 20 77 68 69 6c 65  e same VFS while
1cb90 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
1cba0 6f 64 65 5d 20 77 61 73 20 65 6e 61 62 6c 65 64  ode] was enabled
1cbb0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1cbc0 20 69 66 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d   if both filenam
1cbd0 65 73 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c  es compare equal
1cbe0 20 75 73 69 6e 67 20 6d 65 6d 63 6d 70 28 29 20   using memcmp() 
1cbf0 61 66 74 65 72 20 68 61 76 69 6e 67 20 62 65 65  after having bee
1cc00 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  n.**          pr
1cc10 6f 63 65 73 73 65 64 20 62 79 20 74 68 65 20 5b  ocessed by the [
1cc20 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 78 46  sqlite3_vfs | xF
1cc30 75 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74  ullPathname] met
1cc40 68 6f 64 20 6f 66 20 74 68 65 20 56 46 53 2e 0a  hod of the VFS..
1cc50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
1cc60 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
1cc70 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
1cc80 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1cc90 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
1cca0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
1ccb0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1ccc0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1ccd0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
1cce0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
1ccf0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
1cd00 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1cd10 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1cd20 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
1cd30 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
1cd40 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1cd50 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
1cd60 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1cd70 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
1cd80 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
1cd90 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1cda0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
1cdb0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
1cdc0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1cdd0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1cde0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
1cdf0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1ce00 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
1ce10 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
1ce20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
1ce30 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
1ce40 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
1ce50 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
1ce60 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
1ce70 73 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30 32  s {H12800} <S602
1ce80 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
1ce90 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1cea0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1ceb0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
1cec0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
1ced0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
1cee0 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
1cef0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
1cf00 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
1cf10 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
1cf20 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
1cf30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cf40 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
1cf50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
1cf60 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
1cf70 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
1cf80 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
1cf90 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
1cfa0 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
1cfb0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
1cfc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1cfd0 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
1cfe0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
1cff0 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
1d000 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
1d010 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
1d020 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
1d030 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1d040 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
1d050 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  vely..** Memory 
1d060 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
1d070 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
1d080 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
1d090 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
1d0a0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
1d0b0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
1d0c0 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
1d0d0 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
1d0e0 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
1d0f0 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
1d100 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
1d110 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
1d120 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
1d130 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
1d140 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
1d150 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  nctions..**.** I
1d160 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
1d170 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
1d180 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
1d190 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
1d1a0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
1d1b0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
1d1c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1d1d0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
1d1e0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
1d1f0 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
1d200 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
1d210 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  set..**.** INVAR
1d220 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1d230 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2801} The [sqlit
1d240 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69  e3_errcode(D)] i
1d250 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1d260 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20   the numeric.** 
1d270 20 20 20 20 20 20 20 20 20 5b 72 65 73 75 6c 74           [result
1d280 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
1d290 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
1d2a0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
1d2b0 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  cently.**       
1d2c0 20 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66     failed interf
1d2d0 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61  ace call associa
1d2e0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
1d2f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d300 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  n] D..**.** {H12
1d310 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  803} The [sqlite
1d320 33 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64  3_errmsg(D)] and
1d330 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1d340 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  16(D)].**       
1d350 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
1d360 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
1d370 67 75 61 67 65 20 74 65 78 74 20 74 68 61 74 20  guage text that 
1d380 64 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20  describes.**    
1d390 20 20 20 20 20 20 74 68 65 20 65 72 72 6f 72 20        the error 
1d3a0 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65  in the mostly re
1d3b0 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e  cently failed in
1d3c0 74 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a  terface call,.**
1d3d0 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65            encode
1d3e0 64 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  d as either UTF-
1d3f0 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
1d400 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
1d410 7b 48 31 32 38 30 37 7d 20 54 68 65 20 73 74 72  {H12807} The str
1d420 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1d430 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1d440 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1d450 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20  _errmsg16()].** 
1d460 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c           are val
1d470 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  id until the nex
1d480 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  t SQLite interfa
1d490 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  ce call..**.** {
1d4a0 48 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f  H12808} Calls to
1d4b0 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68   API routines th
1d4c0 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e  at do not return
1d4d0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a   an error code.*
1d4e0 2a 20 20 20 20 20 20 20 20 20 20 28 65 78 61 6d  *          (exam
1d4f0 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  ple: [sqlite3_da
1d500 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20  ta_count()]) do 
1d510 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  not.**          
1d520 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72  change the error
1d530 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 65   code or message
1d540 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1d550 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1d560 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73  3_errcode()], [s
1d570 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1d580 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  , or [sqlite3_er
1d590 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rmsg16()]..**.**
1d5a0 20 7b 48 31 32 38 30 39 7d 20 49 6e 74 65 72 66   {H12809} Interf
1d5b0 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f  aces that are no
1d5c0 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
1d5d0 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  h a specific.** 
1d5e0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1d5f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
1d600 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20  examples:.**    
1d610 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
1d620 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71  printf()] or [sq
1d630 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1d640 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20  red_cache()].** 
1d650 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20           do not 
1d660 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
1d670 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
1d680 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1d690 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
1d6a0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1d6b0 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  ], or [sqlite3_e
1d6c0 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69  rrmsg16()]..*/.i
1d6d0 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
1d6e0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
1d6f0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1d700 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
1d710 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
1d720 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
1d730 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
1d740 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d750 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
1d760 6a 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c 48  ject {H13000} <H
1d770 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  13010>.** KEYWOR
1d780 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
1d790 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
1d7a0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
1d7b0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
1d7c0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
1d7d0 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
1d7e0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
1d7f0 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
1d800 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
1d810 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
1d820 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
1d830 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
1d840 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
1d850 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
1d860 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
1d870 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
1d880 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
1d890 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
1d8a0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1d8b0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
1d8c0 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
1d8d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
1d8e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1d8f0 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
1d900 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
1d910 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
1d920 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
1d930 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
1d940 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
1d950 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
1d960 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
1d970 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
1d980 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1d990 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
1d9a0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
1d9b0 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
1d9c0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1d9d0 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
1d9e0 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
1d9f0 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
1da00 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
1da10 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
1da20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
1da30 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1da40 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
1da50 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
1da60 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
1da70 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
1da80 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
1da90 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1daa0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1dab0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1dac0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
1dad0 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
1dae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1daf0 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48  n-time Limits {H
1db00 31 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a  12760} <S20600>.
1db10 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
1db20 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
1db30 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
1db40 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
1db50 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
1db60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
1db70 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
1db80 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
1db90 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1dba0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1dbb0 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
1dbc0 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
1dbd0 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
1dbe0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1dbf0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
1dc00 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
1dc10 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
1dc20 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
1dc30 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1dc40 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
1dc50 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
1dc60 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
1dc70 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
1dc80 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20  construct.  The 
1dc90 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1dca0 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a   the old limit..
1dcb0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77  **.** If the new
1dcc0 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
1dcd0 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
1dce0 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
1dcf0 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ged..** For the 
1dd00 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f  limit category o
1dd10 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58  f SQLITE_LIMIT_X
1dd20 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 68 61  YZ there is a ha
1dd30 72 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e  rd upper.** boun
1dd40 64 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69  d set by a compi
1dd50 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f  le-time C prepro
1dd60 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d  cessor macro nam
1dd70 65 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59  ed SQLITE_MAX_XY
1dd80 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  Z..** (The "_LIM
1dd90 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
1dda0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
1ddb0 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65  _MAX_".).** Atte
1ddc0 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
1ddd0 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
1dde0 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
1ddf0 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
1de00 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
1de10 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
1de20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  limit..**.** Run
1de30 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65   time limits are
1de40 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
1de50 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
1de60 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
1de70 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
1de80 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
1de90 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
1dea0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
1deb0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
1dec0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
1ded0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
1dee0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
1def0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
1df00 20 77 65 62 62 72 6f 77 73 65 72 20 74 68 61 74   webbrowser that
1df10 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
1df20 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
1df30 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
1df40 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
1df50 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
1df60 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
1df70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
1df80 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
1df90 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
1dfa0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
1dfb0 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
1dfc0 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
1dfd0 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
1dfe0 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
1dff0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
1e000 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
1e010 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
1e020 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
1e030 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
1e040 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
1e050 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
1e060 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
1e070 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
1e080 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1e090 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
1e0a0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
1e0b0 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
1e0c0 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
1e0d0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
1e0e0 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
1e0f0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
1e100 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
1e110 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
1e120 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
1e130 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1e140 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
1e150 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
1e160 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
1e170 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
1e180 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  eases..**.** INV
1e190 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1e1a0 48 31 32 37 36 32 7d 20 41 20 73 75 63 63 65 73  H12762} A succes
1e1b0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1e1c0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c  lite3_limit(D,C,
1e1d0 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 0a 2a  V)] where V is.*
1e1e0 2a 20 20 20 20 20 20 20 20 20 20 70 6f 73 69 74  *          posit
1e1f0 69 76 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ive changes the 
1e200 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a  limit on the siz
1e210 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43  e of construct C
1e220 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
1e230 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
1e240 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 74  nnection] D to t
1e250 68 65 20 6c 65 73 73 65 72 20 6f 66 20 56 20 61  he lesser of V a
1e260 6e 64 20 74 68 65 20 68 61 72 64 20 75 70 70 65  nd the hard uppe
1e270 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6f  r.**          bo
1e280 75 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a 65 20  und on the size 
1e290 6f 66 20 43 20 74 68 61 74 20 69 73 20 73 65 74  of C that is set
1e2a0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1e2b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 36 7d  ..**.** {H12766}
1e2c0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
1e2d0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ll to [sqlite3_l
1e2e0 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65  imit(D,C,V)] whe
1e2f0 72 65 20 56 20 69 73 20 6e 65 67 61 74 69 76 65  re V is negative
1e300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 65 61  .**          lea
1e310 76 65 73 20 74 68 65 20 73 74 61 74 65 20 6f 66  ves the state of
1e320 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1e330 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75 6e 63  onnection] D unc
1e340 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  hanged..**.** {H
1e350 31 32 37 36 39 7d 20 41 20 73 75 63 63 65 73 73  12769} A success
1e360 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1e370 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56  ite3_limit(D,C,V
1e380 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  )] returns the.*
1e390 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
1e3a0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e   of the limit on
1e3b0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e   the size of con
1e3c0 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a  struct C in the.
1e3d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
1e3e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e3f0 5d 20 44 20 61 73 20 69 74 20 77 61 73 20 70 72  ] D as it was pr
1e400 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e  ior to the call.
1e410 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1e420 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
1e430 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
1e440 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
1e450 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1e460 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20  imit Categories 
1e470 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30  {H12790} <H12760
1e480 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
1e490 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
1e4a0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  {limit categorie
1e4b0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
1e4c0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
1e4d0 76 61 72 69 6f 75 73 20 61 73 70 65 63 74 73 20  various aspects 
1e4e0 6f 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  of a [database c
1e4f0 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68  onnection].** th
1e500 61 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 74 65  at can be limite
1e510 64 20 69 6e 20 73 69 7a 65 20 62 79 20 63 61 6c  d in size by cal
1e520 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ls to [sqlite3_l
1e530 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
1e540 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
1e550 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 61  various limits a
1e560 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  re as follows:.*
1e570 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
1e580 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
1e590 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1e5a0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
1e5b0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
1e5c0 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
1e5d0 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20   row.<dd>.**.** 
1e5e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1e5f0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
1e600 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1e610 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
1e620 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c   SQL statement.<
1e630 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1e640 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1e650 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
1e660 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1e670 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1e680 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
1e690 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
1e6a0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
1e6b0 53 45 4c 45 43 54 20 6f 72 20 74 68 65 20 6d 61  SELECT or the ma
1e6c0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1e6d0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
1e6e0 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
1e6f0 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
1e700 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
1e710 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1e720 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
1e730 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1e740 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1e750 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
1e760 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
1e770 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ssion.</dd>.**.*
1e780 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1e790 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
1e7a0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
1e7b0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1e7c0 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
1e7d0 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
1e7e0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a  statement.</dd>.
1e7f0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1e800 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
1e810 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1e820 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1e830 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
1e840 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
1e850 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
1e860 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1e870 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1e880 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1e890 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
1e8a0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
1e8b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1e8c0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
1e8d0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
1e8e0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
1e8f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1e900 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
1e910 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1e920 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 74 74  um number of att
1e930 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 2e  ached databases.
1e940 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1e950 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
1e960 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
1e970 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e980 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
1e990 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
1e9a0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c  rgument to the L
1e9b0 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f  IKE or.** GLOB o
1e9c0 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a  perators.</dd>.*
1e9d0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1e9e0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
1e9f0 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
1ea00 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1ea10 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65  mber of variable
1ea20 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  s in an SQL stat
1ea30 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a  ement that can.*
1ea40 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e  * be bound.</dd>
1ea50 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
1ea60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1ea70 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
1ea80 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
1ea90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1eaa0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
1eab0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
1eac0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1ead0 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
1eae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
1eaf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1eb00 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
1eb10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
1eb20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1eb30 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1eb40 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1eb50 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
1eb60 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
1eb70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1eb80 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
1eb90 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1eba0 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
1ebb0 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
1ebc0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1ebd0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1ebe0 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
1ebf0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1ec00 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
1ec10 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
1ec20 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1ec30 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
1ec40 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41       9../*.** CA
1ec50 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
1ec60 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
1ec70 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c 53 31 30  nt {H13010} <S10
1ec80 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  000>.** KEYWORDS
1ec90 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
1eca0 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a   compiler}.**.**
1ecb0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
1ecc0 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
1ecd0 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
1ece0 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
1ecf0 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
1ed00 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
1ed10 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
1ed20 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
1ed30 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
1ed40 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1ed50 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
1ed60 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
1ed70 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1ed80 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1ed90 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
1eda0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
1edb0 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6()]..**.** The 
1edc0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
1edd0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
1ede0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
1edf0 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
1ee00 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
1ee10 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
1ee20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
1ee30 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
1ee40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
1ee50 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
1ee60 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
1ee70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1ee80 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1ee90 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
1eea0 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
1eeb0 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
1eec0 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74  gument is less t
1eed0 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
1eee0 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
1eef0 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
1ef00 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1ef10 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
1ef20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
1ef30 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
1ef40 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
1ef50 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
1ef60 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65  Sql.  When nByte
1ef70 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1ef80 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
1ef90 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
1efa0 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
1efb0 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
1efc0 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
1efd0 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
1efe0 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
1eff0 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
1f000 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
1f010 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
1f020 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
1f030 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
1f040 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
1f050 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
1f060 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
1f070 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
1f080 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
1f090 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
1f0a0 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
1f0b0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1f0c0 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
1f0d0 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
1f0e0 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
1f0f0 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
1f100 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20  ..**.** *pzTail 
1f110 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1f120 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
1f130 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  te past the end 
1f140 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1f150 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1f160 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
1f170 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70  utines only comp
1f180 69 6c 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a  ile the first.**
1f190 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1f1a0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
1f1b0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1f1c0 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a  to what remains.
1f1d0 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ** uncompiled..*
1f1e0 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20  *.** *ppStmt is 
1f1f0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1f200 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
1f210 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f220 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
1f230 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
1f240 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1f250 20 20 49 66 20 74 68 65 72 65 20 69 73 20 61 6e    If there is an
1f260 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
1f270 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
1f280 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74  L.  If the input
1f290 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
1f2a0 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
1f2b0 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
1f2c0 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
1f2d0 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
1f2e0 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
1f2f0 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30 31 38 7d  ULL..** {A13018}
1f300 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
1f310 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
1f320 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
1f330 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
1f340 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1f350 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1f360 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
1f370 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
1f380 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a  d with it..**.**
1f390 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   On success, [SQ
1f3a0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1f3b0 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65 20  rned, otherwise 
1f3c0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1f3d0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1f3e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
1f3f0 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
1f400 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f410 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
1f420 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
1f430 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
1f440 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
1f450 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
1f460 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
1f470 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
1f480 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
1f490 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
1f4a0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
1f4b0 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e  * In the "v2" in
1f4c0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
1f4d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f4e0 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
1f4f0 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
1f500 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
1f510 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
1f520 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
1f530 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
1f540 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
1f550 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
1f560 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
1f570 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e  ehave a differen
1f580 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a  tly in two ways:
1f590 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
1f5a0 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  li>.** If the da
1f5b0 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
1f5c0 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
1f5d0 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
1f5e0 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
1f5f0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
1f600 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
1f610 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
1f620 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
1f630 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
1f640 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
1f650 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
1f660 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65  in.  If the sche
1f670 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69  ma has changed i
1f680 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20  n.** a way that 
1f690 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d  makes the statem
1f6a0 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61  ent no longer va
1f6b0 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  lid, [sqlite3_st
1f6c0 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c  ep()] will still
1f6d0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1f6e0 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74  TE_SCHEMA].  But
1f6f0 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61   unlike the lega
1f700 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51  cy behavior, [SQ
1f710 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a  LITE_SCHEMA] is.
1f720 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  ** now a fatal e
1f730 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b  rror.  Calling [
1f740 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f750 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c  v2()] again will
1f760 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a   not make the.**
1f770 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20   error go away. 
1f780 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69   Note: use [sqli
1f790 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f  te3_errmsg()] to
1f7a0 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a   find the text.*
1f7b0 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67  * of the parsing
1f7c0 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75   error that resu
1f7d0 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  lts in an [SQLIT
1f7e0 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e  E_SCHEMA] return
1f7f0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
1f800 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e   <li>.** When an
1f810 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
1f820 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f830 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
1f840 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
1f850 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
1f860 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
1f870 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 68 65  ror codes].  The
1f880 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1f890 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
1f8a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
1f8b0 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
1f8c0 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
1f8d0 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
1f8e0 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20  code.** and you 
1f8f0 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
1f900 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
1f910 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1f920 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a  et()] in order.*
1f930 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  * to find the un
1f940 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
1f950 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
1f960 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
1f970 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
1f980 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
1f990 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
1f9a0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
1f9b0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
1f9c0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
1f9d0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  l>.**.** INVARIA
1f9e0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  NTS:.**.** {H130
1f9f0 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
1fa00 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c  _prepare(db,zSql
1fa10 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  ,...)] and.**   
1fa20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1fa30 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
1fa40 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ql,...)] interfa
1fa50 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68  ces interpret th
1fa60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65  e.**          te
1fa70 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c  xt in their zSql
1fa80 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54   parameter as UT
1fa90 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  F-8..**.** {H130
1faa0 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
1fab0 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a 53  _prepare16(db,zS
1fac0 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20  ql,...)] and.** 
1fad0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1fae0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 64  3_prepare16_v2(d
1faf0 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74  b,zSql,...)] int
1fb00 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65  erfaces interpre
1fb10 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
1fb20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20    text in their 
1fb30 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61  zSql parameter a
1fb40 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
1fb50 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1fb60 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 33  r..**.** {H13013
1fb70 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61  } If the nByte a
1fb80 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
1fb90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1fba0 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e  b,zSql,nByte,...
1fbb0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1fbc0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  nd its variants 
1fbd0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
1fbe0 6f 2c 20 74 68 65 20 53 51 4c 20 74 65 78 74 20  o, the SQL text 
1fbf0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  is.**          r
1fc00 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73  ead from zSql is
1fc10 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20   read up to the 
1fc20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
1fc30 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  nator..**.** {H1
1fc40 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e 42 79  3014} If the nBy
1fc50 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  te argument to [
1fc60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fc70 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65  v2(db,zSql,nByte
1fc80 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
1fc90 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61     and its varia
1fca0 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  nts is non-negat
1fcb0 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73  ive, then at mos
1fcc0 74 20 6e 42 79 74 65 73 20 62 79 74 65 73 20 6f  t nBytes bytes o
1fcd0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  f.**          SQ
1fce0 4c 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66  L text is read f
1fcf0 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20  rom zSql..**.** 
1fd00 7b 48 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c  {H13015} In [sql
1fd10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1fd20 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61  db,zSql,N,P,pzTa
1fd30 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  il)] and its var
1fd40 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  iants.**        
1fd50 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e    if the zSql in
1fd60 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1fd70 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
1fd80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
1fd90 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a            and pz
1fda0 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
1fdb0 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  , then *pzTail i
1fdc0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
1fdd0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
1fde0 20 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61     first byte pa
1fdf0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
1fe00 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
1fe10 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a  ement in zSql..*
1fe20 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f  *          <todo
1fe30 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61  >What does *pzTa
1fe40 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74  il point to if t
1fe50 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74  here is one stat
1fe60 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  ement?</todo>.**
1fe70 0a 2a 2a 20 7b 48 31 33 30 31 36 7d 20 41 20 73  .** {H13016} A s
1fe80 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1fe90 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1fea0 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c  re_v2(db,zSql,N,
1feb0 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ppStmt,...)].** 
1fec0 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20           or one 
1fed0 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  of its variants 
1fee0 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53  writes into *ppS
1fef0 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  tmt a pointer to
1ff00 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
1ff10 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
1ff20 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69  tement] or a poi
1ff30 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 69 66 20  nter to NULL if 
1ff40 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  zSql contains.**
1ff50 20 20 20 20 20 20 20 20 20 20 6e 6f 74 68 69 6e            nothin
1ff60 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69  g other than whi
1ff70 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65  tespace or comme
1ff80 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  nts..**.** {H130
1ff90 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
1ffa0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1ffb0 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73  nterface and its
1ffc0 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
1ffd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
1ffe0 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61  LITE_OK] or an a
1fff0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
20000 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69  r code] upon fai
20010 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  lure..**.** {H13
20020 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c  021} Before [sql
20030 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c  ite3_prepare(db,
20040 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d  zSql,nByte,ppStm
20050 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74  t,pzTail)] or it
20060 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  s.**          va
20070 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61  riants returns a
20080 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c  n error (any val
20090 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
200a0 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20  QLITE_OK]),.**  
200b0 20 20 20 20 20 20 20 20 74 68 65 79 20 66 69 72          they fir
200c0 73 74 20 73 65 74 20 2a 70 70 53 74 6d 74 20 74  st set *ppStmt t
200d0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
200e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
200f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
20100 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
20110 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
20120 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
20130 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
20140 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
20150 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
20160 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
20170 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
20180 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
20190 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
201a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
201b0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
201c0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
201d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
201e0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
201f0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
20200 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
20210 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
20220 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
20230 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
20240 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
20250 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
20260 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
20270 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
20280 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
20290 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
202a0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
202b0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
202c0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
202d0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
202e0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
202f0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
20300 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
20310 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
20320 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
20330 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
20340 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
20350 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
20360 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
20370 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
20380 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
20390 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
203a0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
203b0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
203c0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
203d0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
203e0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
203f0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
20400 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
20410 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
20420 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
20430 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
20440 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
20450 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
20460 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
20470 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
20480 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
20490 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
204a0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
204b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
204c0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
204d0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
204e0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
204f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
20500 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
20510 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
20520 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
20530 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
20540 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
20550 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
20560 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
20570 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
20580 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
20590 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
205a0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
205b0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
205c0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
205d0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
205e0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
205f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45  );../*.** CAPIRE
20600 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
20610 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31 33  atement SQL {H13
20620 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 2a  100} <H13000>.**
20630 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
20640 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
20650 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
20660 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
20670 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
20680 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
20690 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
206a0 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
206b0 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
206c0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
206d0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
206e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
206f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
20700 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
20710 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
20720 2a 0a 2a 2a 20 7b 48 31 33 31 30 31 7d 20 49 66  *.** {H13101} If
20730 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
20740 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64  tatement] passed
20750 20 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   as the argument
20760 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
20770 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
20780 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  was compiled usi
20790 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
207a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
207b0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
207c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
207d0 31 36 5f 76 32 28 29 5d 2c 20 74 68 65 6e 20 5b  16_v2()], then [
207e0 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72  sqlite3_sql()] r
207f0 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
20800 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20     a pointer to 
20810 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
20820 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  d string contain
20830 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ing a UTF-8 rend
20840 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ering.**        
20850 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61    of the origina
20860 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  l SQL statement.
20870 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 32 7d 20  .**.** {H13102} 
20880 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  If the [prepared
20890 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73   statement] pass
208a0 65 64 20 61 73 20 74 68 65 20 61 72 67 75 6d 65  ed as the argume
208b0 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  nt to.**        
208c0 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29    [sqlite3_sql()
208d0 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75  ] was compiled u
208e0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
208f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
20900 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
20910 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20920 36 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69  6()], then [sqli
20930 74 65 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 72  te3_sql()] retur
20940 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
20950 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 33  r..**.** {H13103
20960 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74  } The string ret
20970 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
20980 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c  3_sql(S)] is val
20990 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20  id until the.** 
209a0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
209b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
209c0 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  is deleted using
209d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
209e0 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ze(S)]..*/.const
209f0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
20a00 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
20a10 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
20a20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
20a30 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
20a40 65 20 4f 62 6a 65 63 74 20 7b 48 31 35 30 30 30  e Object {H15000
20a50 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45  } <S20200>.** KE
20a60 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
20a70 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20a80 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
20a90 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
20aa0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
20ab0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
20ac0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
20ad0 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
20ae0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
20af0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
20b00 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
20b10 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
20b20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
20b30 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
20b40 65 73 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65  es. Values store
20b50 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
20b60 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
20b70 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
20b80 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
20b90 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
20ba0 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
20bb0 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
20bc0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
20bd0 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
20be0 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
20bf0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
20c00 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
20c10 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
20c20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
20c30 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
20c40 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
20c50 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
20c60 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
20c70 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20c80 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
20c90 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
20ca0 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
20cb0 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
20cc0 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
20cd0 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
20ce0 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
20cf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
20d00 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
20d10 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
20d20 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
20d30 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
20d40 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
20d50 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65  is held.  A inte
20d60 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
20d70 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
20d80 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
20d90 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
20da0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
20db0 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
20dc0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
20dd0 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
20de0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
20df0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
20e00 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
20e10 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
20e20 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
20e30 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
20e40 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
20e50 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
20e60 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
20e70 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
20e80 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
20e90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
20ea0 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
20eb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
20ec0 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
20ed0 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
20ee0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
20ef0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
20f00 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
20f10 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
20f20 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
20f30 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
20f40 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
20f50 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
20f60 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
20f70 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
20f80 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
20f90 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
20fa0 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
20fb0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62  nction between b
20fc0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
20fd0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
20fe0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
20ff0 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
21000 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
21010 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
21020 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
21030 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
21040 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
21050 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
21060 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
21070 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
21080 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
21090 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
210a0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65  rotected..** The
210b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
210c0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
210d0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
210e0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
210f0 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
21100 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
21110 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
21120 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
21130 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
21140 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
21150 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
21160 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
21170 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
21180 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
21190 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
211a0 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
211b0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
211c0 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
211d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
211e0 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
211f0 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
21200 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
21210 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
21220 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
21230 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 31 7d 20  Object {H16001} 
21240 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
21250 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
21260 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
21270 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
21280 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
21290 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
212a0 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74  object.  A point
212b0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
212c0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
212d0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
212e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
212f0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
21300 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
21310 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
21320 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
21330 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
21340 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
21350 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
21360 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
21370 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
21380 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
21390 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
213a0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
213b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
213c0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
213d0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
213e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
213f0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
21400 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
21410 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
21420 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
21430 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
21440 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
21450 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
21460 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
21470 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21480 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
21490 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
214a0 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 7d 20 3c  ments {H13500} <
214b0 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S70300>.** KEYWO
214c0 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
214d0 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
214e0 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
214f0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
21500 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
21510 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
21520 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
21530 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
21540 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c  **.** In the SQL
21550 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74   strings input t
21560 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
21570 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
21580 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
21590 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
215a0 70 6c 61 63 65 64 20 62 79 20 61 20 70 61 72 61  placed by a para
215b0 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66 20  meter in one of 
215c0 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a  these forms:.**.
215d0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
215e0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
215f0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
21600 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
21610 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
21620 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
21630 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73   parameter forms
21640 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e   shown above NNN
21650 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c   is an integer l
21660 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
21670 56 56 20 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e  VV is an alpha-n
21680 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65 72  umeric parameter
21690 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c 75 65   name. The value
216a0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
216b0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
216c0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
216d0 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
216e0 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
216f0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
21700 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
21710 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
21720 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
21730 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
21740 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
21750 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
21760 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
21770 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
21780 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
21790 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
217a0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
217b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
217c0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
217d0 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  ariants..**.** T
217e0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
217f0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
21800 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
21810 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
21820 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  ** The leftmost 
21830 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
21840 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
21850 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20    When the same 
21860 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
21870 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
21880 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
21890 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
218a0 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
218b0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
218c0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
218d0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
218e0 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f  .** The index fo
218f0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
21900 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
21910 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
21920 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
21930 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
21940 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
21950 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20  .  The index.** 
21960 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
21970 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
21980 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68  ue of NNN..** Th
21990 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
219a0 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
219b0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
219c0 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
219d0 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
219e0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
219f0 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
21a00 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
21a10 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
21a20 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
21a30 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
21a40 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
21a50 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
21a60 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
21a70 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
21a80 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
21a90 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
21aa0 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
21ab0 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
21ac0 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
21ad0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
21ae0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
21af0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
21b00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
21b10 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20  aracters..** If 
21b20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
21b30 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
21b40 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
21b50 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
21b60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
21b70 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
21b80 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
21b90 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ator..**.** The 
21ba0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
21bb0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
21bc0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
21bd0 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
21be0 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
21bf0 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
21c00 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
21c10 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
21c20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
21c30 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
21c40 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
21c50 20 69 74 2e 20 49 66 20 74 68 65 20 66 69 66 74   it. If the fift
21c60 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
21c70 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
21c80 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
21c90 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
21ca0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
21cb0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
21cc0 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
21cd0 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
21ce0 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
21cf0 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
21d00 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
21d10 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
21d20 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
21d30 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
21d40 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
21d50 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
21d60 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
21d70 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
21d80 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
21d90 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
21da0 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
21db0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
21dc0 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
21dd0 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
21de0 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
21df0 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
21e00 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20  with zeroes.  A 
21e10 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
21e20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
21e30 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
21e40 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
21e50 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
21e60 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
21e70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
21e80 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
21e90 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
21ea0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
21eb0 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
21ec0 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
21ed0 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
21ee0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
21ef0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
21f00 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
21f10 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61  tines..** A nega
21f20 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
21f30 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
21f40 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
21f50 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
21f60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
21f70 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d  d_*() routines m
21f80 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66  ust be called af
21f90 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ter.** [sqlite3_
21fa0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61  prepare_v2()] (a
21fb0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  nd its variants)
21fc0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
21fd0 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66  et()] and.** bef
21fe0 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ore [sqlite3_ste
21ff0 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67  p()]..** Binding
22000 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
22010 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
22020 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
22030 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70  ne..** Unbound p
22040 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
22050 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
22060 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  L..**.** These r
22070 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
22080 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
22090 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f  ccess or an erro
220a0 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79  r code if.** any
220b0 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
220c0 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  .  [SQLITE_RANGE
220d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
220e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
220f0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
22100 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54  f range.  [SQLIT
22110 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
22120 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
22130 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49   fails..** [SQLI
22140 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74  TE_MISUSE] might
22150 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
22160 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
22170 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a  re called on a.*
22180 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  * virtual machin
22190 65 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72  e that is the wr
221a0 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69  ong state or whi
221b0 63 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62  ch has already b
221c0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a  een finalized..*
221d0 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d  * Detection of m
221e0 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61  isuse is unrelia
221f0 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ble.  Applicatio
22200 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65  ns should not de
22210 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54  pend.** on SQLIT
22220 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73  E_MISUSE returns
22230 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  .  SQLITE_MISUSE
22240 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
22250 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20  indicate a.** a 
22260 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74  logic error in t
22270 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
22280 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
22290 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
222a0 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72  .** panic rather
222b0 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c   than return SQL
222c0 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a  ITE_MISUSE..**.*
222d0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
222e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
222f0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
22300 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
22310 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
22320 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
22330 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
22340 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
22350 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
22360 7b 48 31 33 35 30 36 7d 20 54 68 65 20 5b 53 51  {H13506} The [SQ
22370 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
22380 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73  iler] recognizes
22390 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66   tokens of the f
223a0 6f 72 6d 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  orms.**         
223b0 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24   "?", "?NNN", "$
223c0 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e  VVV", ":VVV", an
223d0 64 20 22 40 56 56 56 22 20 61 73 20 53 51 4c 20  d "@VVV" as SQL 
223e0 70 61 72 61 6d 65 74 65 72 73 2c 0a 2a 2a 20 20  parameters,.**  
223f0 20 20 20 20 20 20 20 20 77 68 65 72 65 20 4e 4e          where NN
22400 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63  N is any sequenc
22410 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  e of one or more
22420 20 64 69 67 69 74 73 0a 2a 2a 20 20 20 20 20 20   digits.**      
22430 20 20 20 20 61 6e 64 20 77 68 65 72 65 20 56 56      and where VV
22440 56 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63  V is any sequenc
22450 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  e of one or more
22460 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 0a 2a 2a   alphanumeric.**
22470 20 20 20 20 20 20 20 20 20 20 63 68 61 72 61 63            charac
22480 74 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74  ters or "::" opt
22490 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64  ionally followed
224a0 20 62 79 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   by a string con
224b0 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20  taining.**      
224c0 20 20 20 20 6e 6f 20 73 70 61 63 65 73 20 61 6e      no spaces an
224d0 64 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68  d contained with
224e0 69 6e 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a  in parentheses..
224f0 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 39 7d 20 54  **.** {H13509} T
22500 68 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65  he initial value
22510 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
22520 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  eter is NULL..**
22530 0a 2a 2a 20 7b 48 31 33 35 31 32 7d 20 54 68 65  .** {H13512} The
22540 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22   index of an "?"
22550 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
22560 73 20 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61  s one larger tha
22570 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
22580 20 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20    largest index 
22590 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
225a0 20 74 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72   to the left, or
225b0 20 31 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20   1 if.**        
225c0 20 20 74 68 65 20 22 3f 22 20 69 73 20 74 68 65    the "?" is the
225d0 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
225e0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
225f0 48 31 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65  H13515} The inde
22600 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53  x of an "?NNN" S
22610 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
22620 74 68 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e  the integer NNN.
22630 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 38 7d 20  .**.** {H13518} 
22640 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  The index of an 
22650 22 3a 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20  ":VVV", "$VVV", 
22660 6f 72 20 22 40 56 56 56 22 20 53 51 4c 20 70 61  or "@VVV" SQL pa
22670 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20  rameter is.**   
22680 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
22690 61 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  as the index of 
226a0 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 65  leftmost occurre
226b0 6e 63 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65  nces of the same
226c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
226d0 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d  ameter, or one m
226e0 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72  ore than the lar
226f0 67 65 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20  gest index over 
22700 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
22710 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
22720 65 20 6c 65 66 74 20 69 66 20 74 68 69 73 20 69  e left if this i
22730 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
22740 72 72 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20  rrence.**       
22750 20 20 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d     of this param
22760 65 74 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68  eter, or 1 if th
22770 69 73 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f  is is the leftmo
22780 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
22790 0a 2a 2a 20 7b 48 31 33 35 32 31 7d 20 54 68 65  .** {H13521} The
227a0 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   [SQL statement 
227b0 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c 73 20  compiler] fails 
227c0 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f  with an [SQLITE_
227d0 52 41 4e 47 45 5d 0a 2a 2a 20 20 20 20 20 20 20  RANGE].**       
227e0 20 20 20 65 72 72 6f 72 20 69 66 20 74 68 65 20     error if the 
227f0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
22800 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
22810 73 20 74 68 61 6e 20 31 0a 2a 2a 20 20 20 20 20  s than 1.**     
22820 20 20 20 20 20 6f 72 20 67 72 65 61 74 65 72 20       or greater 
22830 74 68 61 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  than the compile
22840 2d 74 69 6d 65 20 53 51 4c 49 54 45 5f 4d 41 58  -time SQLITE_MAX
22850 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
22860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
22870 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ameter..**.** {H
22880 31 33 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20  13524} Calls to 
22890 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
228a0 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
228b0 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a  d(S,N,V,...)].**
228c0 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69            associ
228d0 61 74 65 20 74 68 65 20 76 61 6c 75 65 20 56 20  ate the value V 
228e0 77 69 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72  with all SQL par
228f0 61 6d 65 74 65 72 73 20 68 61 76 69 6e 67 20 61  ameters having a
22900 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  n.**          in
22910 64 65 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20  dex of N in the 
22920 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22930 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ent] S..**.** {H
22940 31 33 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20  13527} Calls to 
22950 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
22960 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
22970 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  d(S,N,...)].**  
22980 20 20 20 20 20 20 20 20 6f 76 65 72 72 69 64 65          override
22990 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74   prior calls wit
229a0 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  h the same value
229b0 73 20 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a  s of S and N..**
229c0 0a 2a 2a 20 7b 48 31 33 35 33 30 7d 20 42 69 6e  .** {H13530} Bin
229d0 64 69 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65  dings establishe
229e0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69  d by [sqlite3_bi
229f0 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
22a00 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a  3_bind(S,...)].*
22a10 2a 20 20 20 20 20 20 20 20 20 20 70 65 72 73 69  *          persi
22a20 73 74 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20  st across calls 
22a30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
22a40 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  t(S)]..**.** {H1
22a50 33 35 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3533} In calls t
22a60 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
22a70 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
22a80 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
22a90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
22aa0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
22ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
22ac0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
22ad0 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51  6(S,N,V,L,D)] SQ
22ae0 4c 69 74 65 20 62 69 6e 64 73 20 74 68 65 20 66  Lite binds the f
22af0 69 72 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20  irst L.**       
22b00 20 20 20 62 79 74 65 73 20 6f 66 20 74 68 65 20     bytes of the 
22b10 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 70  BLOB or string p
22b20 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20  ointed to by V, 
22b30 77 68 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20  when L.**       
22b40 20 20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69     is non-negati
22b50 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33  ve..**.** {H1353
22b60 36 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  6} In calls to [
22b70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
22b80 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72  t(S,N,V,L,D)] or
22b90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
22ba0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
22bb0 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51  6(S,N,V,L,D)] SQ
22bc0 4c 69 74 65 20 62 69 6e 64 73 20 63 68 61 72 61  Lite binds chara
22bd0 63 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  cters.**        
22be0 20 20 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68    from V through
22bf0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
22c00 63 68 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c  character when L
22c10 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a   is negative..**
22c20 0a 2a 2a 20 7b 48 31 33 35 33 39 7d 20 49 6e 20  .** {H13539} In 
22c30 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
22c40 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
22c50 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
22c60 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
22c70 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
22c80 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
22c90 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
22ca0 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
22cb0 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74  ,D)] when D is t
22cc0 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20  he special.**   
22cd0 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20         constant 
22ce0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
22cf0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
22d00 74 68 61 74 20 74 68 65 20 76 61 6c 75 65 20 56  that the value V
22d10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
22d20 68 65 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75  held in static u
22d30 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 74  nmanaged space t
22d40 68 61 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61  hat will not cha
22d50 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nge.**          
22d60 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
22d70 69 6d 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69  ime of the bindi
22d80 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34  ng..**.** {H1354
22d90 32 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  2} In calls to [
22da0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
22db0 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a  b(S,N,V,L,D)],.*
22dc0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
22dd0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
22de0 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  N,V,L,D)], or.**
22df0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
22e00 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
22e10 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20  ,N,V,L,D)] when 
22e20 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  D is the special
22e30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
22e40 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52  stant [SQLITE_TR
22e50 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f  ANSIENT], the ro
22e60 75 74 69 6e 65 20 6d 61 6b 65 73 20 61 0a 2a 2a  utine makes a.**
22e70 20 20 20 20 20 20 20 20 20 20 70 72 69 76 61 74            privat
22e80 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 61  e copy of the va
22e90 6c 75 65 20 56 20 62 65 66 6f 72 65 20 69 74 20  lue V before it 
22ea0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b  returns..**.** {
22eb0 48 31 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c 73  H13545} In calls
22ec0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
22ed0 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
22ee0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
22ef0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
22f00 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
22f10 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
22f20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
22f30 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
22f40 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f 69 6e  when D is a poin
22f50 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
22f60 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20 53     a function, S
22f70 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
22f80 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64  at function to d
22f90 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20  estroy the.**   
22fa0 20 20 20 20 20 20 20 76 61 6c 75 65 20 56 20 61         value V a
22fb0 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
22fc0 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 76  shed using the v
22fd0 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48  alue V..**.** {H
22fe0 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73 20  13548} In calls 
22ff0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
23000 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  _zeroblob(S,N,V,
23010 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20 62 6f  L)] the value bo
23020 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  und.**          
23030 69 73 20 61 20 42 4c 4f 42 20 6f 66 20 4c 20 62  is a BLOB of L b
23040 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d  ytes, or a zero-
23050 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 66 20 4c  length BLOB if L
23060 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a   is negative..**
23070 0a 2a 2a 20 7b 48 31 33 35 35 31 7d 20 49 6e 20  .** {H13551} In 
23080 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
23090 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c 4e  3_bind_value(S,N
230a0 2c 56 29 5d 20 74 68 65 20 56 20 61 72 67 75 6d  ,V)] the V argum
230b0 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20 20  ent may.**      
230c0 20 20 20 20 62 65 20 65 69 74 68 65 72 20 61 20      be either a 
230d0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
230e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
230f0 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20   or an.**       
23100 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20     [unprotected 
23110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
23120 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  bject..*/.int sq
23130 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
23140 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
23150 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
23160 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
23170 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
23180 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
23190 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
231a0 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
231b0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
231c0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
231d0 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
231e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
231f0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
23200 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
23210 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
23220 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
23230 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23240 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
23250 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
23260 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
23270 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
23280 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
23290 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
232a0 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
232b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
232c0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
232d0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
232e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
232f0 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
23300 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
23310 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
23320 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
23330 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
23340 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
23350 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
23360 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
23370 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
23380 72 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30  rs {H13600} <S70
23390 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  300>.**.** This 
233a0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
233b0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
233c0 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
233d0 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
233e0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
233f0 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
23400 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
23410 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
23420 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
23430 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
23440 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
23450 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
23460 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
23470 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
23480 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
23490 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
234a0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
234b0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
234c0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
234d0 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
234e0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
234f0 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
23500 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
23510 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
23520 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
23530 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
23540 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
23550 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
23560 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
23570 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
23580 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c  e ?NNN are used,
23590 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
235a0 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
235b0 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  t..**.** See als
235c0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
235d0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
235e0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
235f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
23600 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
23610 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
23620 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
23630 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
23640 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
23650 36 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  601} The [sqlite
23660 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
23670 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
23680 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
23690 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 61 72           the lar
236a0 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c  gest index of al
236b0 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  l SQL parameters
236c0 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
236d0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
236e0 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30  atement] S, or 0
236f0 20 69 66 20 53 20 63 6f 6e 74 61 69 6e 73 20 6e   if S contains n
23700 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  o SQL parameters
23710 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23720 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
23730 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
23740 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
23750 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
23760 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20   Host Parameter 
23770 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30  {H13620} <S70300
23780 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
23790 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
237a0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61  ointer to the na
237b0 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a  me of the n-th.*
237c0 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  * [SQL parameter
237d0 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] in a [prepared
237e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
237f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
23800 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
23810 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
23820 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
23830 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
23840 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
23850 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
23860 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
23870 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
23880 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
23890 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
238a0 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
238b0 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
238c0 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
238d0 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
238e0 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65  ame..** Paramete
238f0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
23900 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
23910 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
23920 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
23930 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65  nd are also refe
23940 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e  rred to as "anon
23950 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
23960 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  "..**.** The fir
23970 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
23980 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
23990 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
239a0 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e  * If the value n
239b0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
239c0 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20   or if the n-th 
239d0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
239e0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
239f0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
23a00 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73    The returned s
23a10 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
23a20 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
23a30 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
23a40 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
23a50 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
23a60 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
23a70 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
23a80 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
23a90 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
23aa0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
23ab0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
23ac0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
23ad0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
23ae0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
23af0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
23b00 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
23b10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
23b20 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
23b30 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
23b40 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 32  TS:.**.** {H1362
23b50 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
23b60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
23b70 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
23b80 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
23b90 20 20 20 20 20 20 20 20 61 20 55 54 46 2d 38 20          a UTF-8 
23ba0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
23bb0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
23bc0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a   parameter in.**
23bd0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
23be0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23bf0 74 5d 20 53 20 68 61 76 69 6e 67 20 69 6e 64 65  t] S having inde
23c00 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  x N, or.**      
23c10 20 20 20 20 4e 55 4c 4c 20 69 66 20 74 68 65 72      NULL if ther
23c20 65 20 69 73 20 6e 6f 20 53 51 4c 20 70 61 72 61  e is no SQL para
23c30 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78  meter with index
23c40 20 4e 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20   N or if the.** 
23c50 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
23c60 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20  er with index N 
23c70 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20  is an anonymous 
23c80 70 61 72 61 6d 65 74 65 72 20 22 3f 22 2e 0a 2a  parameter "?"..*
23c90 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
23ca0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
23cb0 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
23cc0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
23cd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23ce0 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
23cf0 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
23d00 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20  n Name {H13640} 
23d10 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52  <S70300>.**.** R
23d20 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
23d30 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
23d40 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
23d50 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65  me.  The.** inde
23d60 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
23d70 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
23d80 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
23d90 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
23da0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
23db0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
23dc0 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a  nd()].  A zero.*
23dd0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
23de0 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
23df0 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
23e00 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a    The parameter.
23e10 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
23e20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
23e30 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
23e40 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
23e50 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
23e60 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
23e70 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
23e80 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
23e90 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
23ea0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
23eb0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
23ec0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
23ed0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
23ee0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
23ef0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
23f00 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
23f10 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
23f20 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 34 31  S:.**.** {H13641
23f30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
23f40 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
23f50 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  dex(S,N)] interf
23f60 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
23f70 20 20 20 20 20 20 20 20 74 68 65 20 69 6e 64 65          the inde
23f80 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74  x of SQL paramet
23f90 65 72 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  er in the [prepa
23fa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
23fb0 2a 20 20 20 20 20 20 20 20 20 20 53 20 77 68 6f  *          S who
23fc0 73 65 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20  se name matches 
23fd0 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67  the UTF-8 string
23fe0 20 4e 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72   N, or 0 if ther
23ff0 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  e is.**         
24000 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e   no match..*/.in
24010 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
24020 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
24030 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
24040 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
24050 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24060 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
24070 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
24080 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48  red Statement {H
24090 31 33 36 36 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13660} <S70300>.
240a0 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74  **.** Contrary t
240b0 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
240c0 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
240d0 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
240e0 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
240f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
24100 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
24110 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
24120 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73  tatement]..** Us
24130 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
24140 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
24150 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
24160 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ULL..**.** INVAR
24170 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
24180 33 36 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3661} The [sqlit
24190 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
241a0 73 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  s(S)] interface 
241b0 72 65 73 65 74 73 20 61 6c 6c 20 53 51 4c 0a 2a  resets all SQL.*
241c0 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
241d0 65 74 65 72 20 62 69 6e 64 69 6e 67 73 20 69 6e  eter bindings in
241e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
241f0 74 61 74 65 6d 65 6e 74 5d 20 53 20 62 61 63 6b  tatement] S back
24200 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
24210 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
24220 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
24230 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
24240 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
24250 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
24260 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37  Result Set {H137
24270 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  10} <S10700>.**.
24280 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75  ** Return the nu
24290 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
242a0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
242b0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
242c0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
242d0 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20  tatement]. This 
242e0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
242f0 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
24300 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
24310 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
24320 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
24330 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
24340 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ATE])..**.** INV
24350 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
24360 48 31 33 37 31 31 7d 20 54 68 65 20 5b 73 71 6c  H13711} The [sql
24370 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
24380 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
24390 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
243a0 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
243b0 20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65    columns in the
243c0 20 72 65 73 75 6c 74 20 73 65 74 20 67 65 6e 65   result set gene
243d0 72 61 74 65 64 20 62 79 20 74 68 65 20 5b 70 72  rated by the [pr
243e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
243f0 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] S,.**         
24400 20 6f 72 20 30 20 69 66 20 53 20 64 6f 65 73 20   or 0 if S does 
24410 6e 6f 74 20 67 65 6e 65 72 61 74 65 20 61 20 72  not generate a r
24420 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e  esult set..*/.in
24430 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
24440 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
24450 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
24460 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
24470 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
24480 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37  Result Set {H137
24490 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  20} <S10700>.**.
244a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
244b0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
244c0 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
244d0 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
244e0 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
244f0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
24500 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
24510 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
24520 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
24530 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
24540 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
24550 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
24560 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
24570 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
24580 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
24590 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
245a0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
245b0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
245c0 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ng.  The first p
245d0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
245e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
245f0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
24600 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
24610 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
24620 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
24630 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
24640 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54  olumn number.  T
24650 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
24660 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
24670 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  **.** The return
24680 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
24690 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
246a0 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
246b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
246c0 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
246d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
246e0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
246f0 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
24700 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
24710 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
24720 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
24730 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
24740 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
24750 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
24760 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
24770 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
24780 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
24790 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
247a0 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
247b0 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
247c0 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
247d0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
247e0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
247f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
24800 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
24810 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
24820 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
24830 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
24840 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
24850 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
24860 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
24870 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
24880 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
24890 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
248a0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
248b0 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
248c0 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
248d0 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
248e0 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  t..**.** INVARIA
248f0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  NTS:.**.** {H137
24900 32 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  21} A successful
24910 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
24920 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
24930 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a  mn_name(S,N)].**
24940 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
24950 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
24960 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20  name of the Nth 
24970 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20  column (where 0 
24980 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  is.**          t
24990 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
249a0 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73 75  mn) for the resu
249b0 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a  lt set of the.**
249c0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
249d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
249e0 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   as a zero-termi
249f0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
24a00 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32  ng..**.** {H1372
24a10 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  3} A successful 
24a20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
24a30 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
24a40 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a  n_name16(S,N)].*
24a50 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
24a60 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
24a70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 68   name of the Nth
24a80 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30   column (where 0
24a90 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
24aa0 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  the leftmost col
24ab0 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73  umn) for the res
24ac0 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a 2a  ult set of the.*
24ad0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
24ae0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24af0 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  S as a zero-term
24b00 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 73 74  inated UTF-16 st
24b10 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
24b20 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
24b30 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
24b40 20 7b 48 31 33 37 32 34 7d 20 54 68 65 20 5b 73   {H13724} The [s
24b50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
24b60 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  me()] and [sqlit
24b70 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
24b80 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
24b90 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72  interfaces retur
24ba0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
24bb0 20 69 66 20 74 68 65 79 20 61 72 65 20 75 6e 61   if they are una
24bc0 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ble to.**       
24bd0 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f     allocate memo
24be0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 69 72  ry to hold their
24bf0 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72 6e 20 73   normal return s
24c00 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  trings..**.** {H
24c10 31 33 37 32 35 7d 20 49 66 20 74 68 65 20 4e 20  13725} If the N 
24c20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
24c30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
24c40 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20  e(S,N)] or.**   
24c50 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
24c60 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
24c70 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66 20 72 61  N)] is out of ra
24c80 6e 67 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  nge, then the.**
24c90 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
24ca0 61 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55  aces return a NU
24cb0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
24cc0 2a 20 7b 48 31 33 37 32 36 7d 20 54 68 65 20 73  * {H13726} The s
24cd0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
24ce0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
24cf0 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e  mn_name(S,N)] an
24d00 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
24d10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
24d20 6d 65 31 36 28 53 2c 4e 29 5d 20 61 72 65 20 76  me16(S,N)] are v
24d30 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e  alid until the n
24d40 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ext.**          
24d50 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 72  call to either r
24d60 6f 75 74 69 6e 65 20 77 69 74 68 20 74 68 65 20  outine with the 
24d70 73 61 6d 65 20 53 20 61 6e 64 20 4e 20 70 61 72  same S and N par
24d80 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  ameters.**      
24d90 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71      or until [sq
24da0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
24db0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a  )] is called..**
24dc0 0a 2a 2a 20 7b 48 31 33 37 32 37 7d 20 57 68 65  .** {H13727} Whe
24dd0 6e 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  n a result colum
24de0 6e 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  n of a [SELECT] 
24df0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69  statement contai
24e00 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
24e10 6e 20 41 53 20 63 6c 61 75 73 65 2c 20 74 68 65  n AS clause, the
24e20 20 6e 61 6d 65 20 6f 66 20 74 68 61 74 20 63 6f   name of that co
24e30 6c 75 6d 6e 20 69 73 20 74 68 65 20 69 64 65 6e  lumn is the iden
24e40 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 20 20 20  tifier.**       
24e50 20 20 20 74 6f 20 74 68 65 20 72 69 67 68 74 20     to the right 
24e60 6f 66 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72  of the AS keywor
24e70 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
24e80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
24e90 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
24ea0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
24eb0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
24ec0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
24ed0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24ee0 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
24ef0 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
24f00 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
24f10 20 52 65 73 75 6c 74 20 7b 48 31 33 37 34 30 7d   Result {H13740}
24f20 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
24f30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
24f40 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
24f50 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74  o determine what
24f60 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a   column of what.
24f70 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63  ** table in whic
24f80 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73  h database a res
24f90 75 6c 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  ult of a [SELECT
24fa0 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65  ] statement come
24fb0 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e  s from..** The n
24fc0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
24fd0 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
24fe0 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
24ff0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
25000 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
25010 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54  TF-16 string.  T
25020 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
25030 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
25040 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
25050 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
25060 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
25070 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
25080 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
25090 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
250a0 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
250b0 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  me..** The retur
250c0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
250d0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
250e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
250f0 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
25100 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
25110 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
25120 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
25130 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
25140 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
25150 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
25160 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
25170 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72   The names retur
25180 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
25190 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
251a0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
251b0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
251c0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
251d0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
251e0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c  ument to the fol
251f0 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20  lowing calls is 
25200 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
25210 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65  ement]..** These
25220 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
25230 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
25240 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  out the Nth colu
25250 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
25260 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
25270 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
25280 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
25290 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
252a0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
252b0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
252c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
252d0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
252e0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
252f0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
25300 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
25310 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
25320 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
25330 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  L.  These routin
25340 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
25350 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
25360 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
25370 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
25380 20 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65    Otherwise, the
25390 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
253a0 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
253b0 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
253c0 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  e.** and column 
253d0 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
253e0 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
253f0 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
25400 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  ** As with all o
25410 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
25420 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65  , those postfixe
25430 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
25440 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
25450 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68  oded strings, th
25460 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
25470 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20  s return UTF-8. 
25480 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  {END}.**.** Thes
25490 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
254a0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
254b0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
254c0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
254d0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
254e0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
254f0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
25500 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
25510 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a  .**.** {A13751}.
25520 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
25530 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
25540 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
25550 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
25560 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
25570 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25580 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
25590 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
255a0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
255b0 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
255c0 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
255d0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  NTS:.**.** {H137
255e0 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
255f0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
25600 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _name(S,N)] inte
25610 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
25620 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
25630 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d   the UTF-8 zero-
25640 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
25650 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
25660 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a  from which the.*
25670 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
25680 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
25690 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
256a0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78  atement] S is ex
256b0 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20  tracted,.**     
256c0 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20       or NULL if 
256d0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
256e0 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
256f0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
25700 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
25710 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
25720 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
25730 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
25740 20 7b 48 31 33 37 34 32 7d 20 54 68 65 20 5b 73   {H13742} The [s
25750 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
25760 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c  tabase_name16(S,
25770 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
25780 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
25790 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
257a0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
257b0 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69  order zero-termi
257c0 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
257d0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20  e database.**   
257e0 20 20 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63         from whic
257f0 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  h the Nth result
25800 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b   column of the [
25810 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25820 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20  nt] S is.**     
25830 20 20 20 20 20 65 78 74 72 61 63 74 65 64 2c 20       extracted, 
25840 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
25850 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
25860 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
25870 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ession.**       
25880 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20     or if unable 
25890 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
258a0 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ry to store the 
258b0 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  name..**.** {H13
258c0 37 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  743} The [sqlite
258d0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
258e0 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
258f0 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
25900 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
25910 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  he UTF-8 zero-te
25920 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
25930 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20   the table from 
25940 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20  which the.**    
25950 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74        Nth result
25960 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b   column of the [
25970 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25980 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74  nt] S is extract
25990 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed,.**          
259a0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
259b0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
259c0 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
259d0 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ession.**       
259e0 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20     or if unable 
259f0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
25a00 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ry to store the 
25a10 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  name..**.** {H13
25a20 37 34 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  744} The [sqlite
25a30 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
25a40 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65  ame16(S,N)] inte
25a50 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
25a60 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
25a70 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69   the UTF-16 nati
25a80 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65  ve byte order ze
25a90 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
25aa0 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  me of the table.
25ab0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
25ac0 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72   which the Nth r
25ad0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
25ae0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25af0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a  atement] S is.**
25b00 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63            extrac
25b10 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
25b20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
25b30 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
25b40 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
25b50 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
25b60 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
25b70 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
25b80 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
25b90 20 7b 48 31 33 37 34 35 7d 20 54 68 65 20 5b 73   {H13745} The [s
25ba0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
25bb0 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  igin_name(S,N)] 
25bc0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
25bd0 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
25be0 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a       the UTF-8 z
25bf0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
25c00 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ame of the table
25c10 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69   column from whi
25c20 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ch the.**       
25c30 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f     Nth result co
25c40 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65  lumn of the [pre
25c50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25c60 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c   S is extracted,
25c70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
25c80 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20  NULL if the Nth 
25c90 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
25ca0 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
25cb0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
25cc0 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
25cd0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
25ce0 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
25cf0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 36  e..**.** {H13746
25d00 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
25d10 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
25d20 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  e16(S,N)] interf
25d30 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
25d40 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
25d50 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  he UTF-16 native
25d60 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f   byte order zero
25d70 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
25d80 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
25d90 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e            column
25da0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
25db0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
25dc0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  n of the.**     
25dd0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
25de0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65  tatement] S is e
25df0 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
25e00 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
25e10 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  umn.**          
25e20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
25e30 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  l expression or 
25e40 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
25e50 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ocate memory.** 
25e60 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72           to stor
25e70 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
25e80 2a 20 7b 48 31 33 37 34 38 7d 20 54 68 65 20 72  * {H13748} The r
25e90 65 74 75 72 6e 20 76 61 6c 75 65 73 20 66 72 6f  eturn values fro
25ea0 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  m.**          [s
25eb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
25ec0 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
25ed0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
25ee0 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20  terfaces].**    
25ef0 20 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 20        are valid 
25f00 66 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d 65  for the lifetime
25f10 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
25f20 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
25f30 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69           or unti
25f40 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  l the encoding i
25f50 73 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e 6f  s changed by ano
25f60 74 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a 2a  ther metadata.**
25f70 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
25f80 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68 65  ace call for the
25f90 20 73 61 6d 65 20 70 72 65 70 61 72 65 64 20 73   same prepared s
25fa0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
25fb0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  umn..**.** ASSUM
25fc0 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
25fd0 31 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f 72  13751} If two or
25fe0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
25ff0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
26000 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
26010 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
26020 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
26030 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
26040 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20  faces].**       
26050 20 20 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20     for the same 
26060 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26070 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
26080 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20  column.**       
26090 20 20 20 61 74 20 74 68 65 20 73 61 6d 65 20 74     at the same t
260a0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
260b0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
260c0 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
260d0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
260e0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
260f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
26100 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
26110 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
26120 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
26130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
26140 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
26150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
26160 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
26170 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
26180 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
26190 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
261a0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
261b0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
261c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
261d0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
261e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
261f0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
26200 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
26210 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
26220 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
26230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26240 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
26250 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
26260 65 73 75 6c 74 20 7b 48 31 33 37 36 30 7d 20 3c  esult {H13760} <
26270 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
26280 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
26290 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
262a0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
262b0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
262c0 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
262d0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
262e0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
262f0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
26300 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
26310 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
26320 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
26330 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
26340 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
26350 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
26360 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
26370 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
26380 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20  s returned.  If 
26390 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
263a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
263b0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
263c0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
263d0 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
263e0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
263f0 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  d..** The return
26400 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
26410 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
26420 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46  d. {END}.**.** F
26430 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
26440 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
26450 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
26460 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
26470 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
26480 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
26490 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
264a0 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
264b0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
264c0 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
264d0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
264e0 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
264f0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
26500 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
26510 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
26520 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
26530 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
26540 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
26550 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
26560 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
26570 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
26580 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20  ime typing.  So 
26590 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
265a0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
265b0 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
265c0 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
265d0 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
265e0 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
265f0 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
26600 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
26610 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
26620 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
26630 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
26640 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
26650 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
26660 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20  ic.  Type.** is 
26670 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
26680 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
26690 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
266a0 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
266b0 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
266c0 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49   values..**.** I
266d0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
266e0 20 7b 48 31 33 37 36 31 7d 20 20 41 20 73 75 63   {H13761}  A suc
266f0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
26700 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26710 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 72  decltype(S,N)] r
26720 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20  eturns a.**     
26730 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
26740 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
26750 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
26760 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74  e declared datat
26770 79 70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ype.**          
26780 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
26790 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72  lumn that appear
267a0 73 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c  s as the Nth col
267b0 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 0a 2a 2a  umn (numbered.**
267c0 20 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20             from 
267d0 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  0) of the result
267e0 20 73 65 74 20 74 6f 20 74 68 65 20 5b 70 72 65   set to the [pre
267f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26800 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36   S..**.** {H1376
26810 32 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c  2}  A successful
26820 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
26830 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
26840 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20  e16(S,N)].**    
26850 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
26860 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
26870 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
26880 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67  yte order string
26890 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f  .**           co
268a0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63  ntaining the dec
268b0 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 20 6f  lared datatype o
268c0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
268d0 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 0a  mn that appears.
268e0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20  **           as 
268f0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
26900 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29  numbered from 0)
26910 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
26920 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  et to the.**    
26930 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
26940 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
26950 2a 0a 2a 2a 20 7b 48 31 33 37 36 33 7d 20 20 49  *.** {H13763}  I
26960 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
26970 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74   0 or N is great
26980 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  er than or equal
26990 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
269a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
269b0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b 70  olumns in the [p
269c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
269d0 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  t] S,.**        
269e0 20 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74 68     or if the Nth
269f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
26a00 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
26a10 20 73 75 62 71 75 65 72 79 20 72 61 74 68 65 72   subquery rather
26a20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
26a30 61 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  an a table colum
26a40 6e 2c 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  n, or if a memor
26a50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
26a60 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  lure.**         
26a70 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20    occurs during 
26a80 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73  encoding convers
26a90 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  ions, then.**   
26aa0 20 20 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f          calls to
26ab0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26ac0 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20  _decltype(S,N)] 
26ad0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
26ae0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26af0 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d  decltype16(S,N)]
26b00 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f   return NULL..*/
26b10 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
26b20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
26b30 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
26b40 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
26b50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
26b60 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
26b70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
26b80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26b90 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
26ba0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48  SQL Statement {H
26bb0 31 33 32 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a  13200} <S10000>.
26bc0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
26bd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26be0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
26bf0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
26c00 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
26c10 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
26c20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26c30 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
26c40 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
26c50 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
26c60 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
26c70 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
26c80 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
26c90 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
26ca0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
26cb0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
26cc0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
26cd0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
26ce0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
26cf0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
26d00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
26d10 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
26d20 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
26d30 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
26d40 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
26d50 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
26d60 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
26d70 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
26d80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
26d90 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
26da0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
26db0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
26dc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
26dd0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
26de0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
26df0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
26e00 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
26e10 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
26e20 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
26e30 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
26e40 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
26e50 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
26e60 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
26e70 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  d..**.** In the 
26e80 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
26e90 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
26ea0 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
26eb0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
26ec0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
26ed0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
26ee0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
26ef0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
26f00 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  SE]..** With the
26f10 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
26f20 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
26f30 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
26f40 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
26f50 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
26f60 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
26f70 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
26f80 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
26f90 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
26fa0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
26fb0 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
26fc0 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
26fd0 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
26fe0 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
26ff0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
27000 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
27010 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
27020 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
27030 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
27040 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
27050 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
27060 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
27070 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
27080 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
27090 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a  ccurs within a.*
270a0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
270b0 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
270c0 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
270d0 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
270e0 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
270f0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  uing..**.** [SQL
27100 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
27110 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
27120 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
27130 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
27140 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
27150 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
27160 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
27170 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
27180 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
27190 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
271a0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
271b0 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
271c0 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
271d0 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
271e0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
271f0 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  te..**.** If the
27200 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
27210 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
27220 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
27230 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
27240 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
27250 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
27260 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
27270 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
27280 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
27290 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
272a0 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
272b0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
272c0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
272d0 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
272e0 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
272f0 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
27300 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
27310 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
27320 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
27330 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
27340 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
27350 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
27360 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
27370 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
27380 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
27390 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
273a0 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
273b0 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
273c0 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
273d0 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
273e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
273f0 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  )]..** With the 
27400 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
27410 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
27420 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
27430 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
27440 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
27450 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
27460 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
27470 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
27480 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
27490 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
274a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
274b0 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
274c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
274d0 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20  ].  In the "v2" 
274e0 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
274f0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
27500 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
27510 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
27520 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
27530 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
27540 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
27550 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
27560 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
27570 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
27580 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
27590 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
275a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
275b0 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
275c0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
275d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
275e0 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
275f0 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
27600 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
27610 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
27620 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
27630 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
27640 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
27650 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
27660 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
27670 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
27680 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
27690 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
276a0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
276b0 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c  in time..**.** <
276c0 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
276d0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
276e0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
276f0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
27700 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
27710 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
27720 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
27730 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
27740 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
27750 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
27760 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
27770 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
27780 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
27790 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
277a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
277b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
277c0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
277d0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
277e0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
277f0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
27800 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
27810 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
27820 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
27830 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
27840 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
27850 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
27860 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
27870 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
27880 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
27890 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
278a0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
278b0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
278c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
278d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
278e0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
278f0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
27900 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
27910 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
27920 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
27930 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
27940 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
27950 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
27960 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
27970 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
27980 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
27990 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
279a0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
279b0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
279c0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
279d0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 32 30  TS:.**.** {H1320
279e0 32 7d 20 20 49 66 20 74 68 65 20 5b 70 72 65 70  2}  If the [prep
279f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27a00 53 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65  S is ready to be
27a10 20 72 75 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20   run, then.**   
27a20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
27a30 5f 73 74 65 70 28 53 29 5d 20 61 64 76 61 6e 63  _step(S)] advanc
27a40 65 73 20 74 68 61 74 20 70 72 65 70 61 72 65 64  es that prepared
27a50 20 73 74 61 74 65 6d 65 6e 74 20 75 6e 74 69 6c   statement until
27a60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f  .**           co
27a70 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69  mpletion or unti
27a80 6c 20 69 74 20 69 73 20 72 65 61 64 79 20 74 6f  l it is ready to
27a90 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20   return another 
27aa0 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  row of the.**   
27ab0 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
27ac0 65 74 2c 20 6f 72 20 75 6e 74 69 6c 20 61 6e 20  et, or until an 
27ad0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
27ae0 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 0a  pt | interrupt].
27af0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20  **           or 
27b00 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
27b10 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b   occurs..**.** {
27b20 48 31 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20  H15304}  When a 
27b30 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
27b40 5f 73 74 65 70 28 53 29 5d 20 63 61 75 73 65 73  _step(S)] causes
27b50 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
27b60 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20  tatement].**    
27b70 20 20 20 20 20 20 20 53 20 74 6f 20 72 75 6e 20         S to run 
27b80 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 20 74  to completion, t
27b90 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
27ba0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  rns [SQLITE_DONE
27bb0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 36  ]..**.** {H15306
27bc0 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74  }  When a call t
27bd0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
27be0 53 29 5d 20 73 74 6f 70 73 20 62 65 63 61 75 73  S)] stops becaus
27bf0 65 20 69 74 20 69 73 20 72 65 61 64 79 20 74 6f  e it is ready to
27c00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
27c10 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77  turn another row
27c20 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
27c30 65 74 2c 20 69 74 20 72 65 74 75 72 6e 73 20 5b  et, it returns [
27c40 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a  SQLITE_ROW]..**.
27c50 2a 2a 20 7b 48 31 35 33 30 38 7d 20 20 49 66 20  ** {H15308}  If 
27c60 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
27c70 65 33 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 6f  e3_step(S)] enco
27c80 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20  unters an.**    
27c90 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
27ca0 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65  interrupt | inte
27cb0 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d  rrupt] or a run-
27cc0 74 69 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20  time error,.**  
27cd0 20 20 20 20 20 20 20 20 20 69 74 20 72 65 74 75           it retu
27ce0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
27cf0 74 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 68  te error code th
27d00 61 74 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  at is not one of
27d10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
27d20 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49  QLITE_OK], [SQLI
27d30 54 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c  TE_ROW], or [SQL
27d40 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a  ITE_DONE]..**.**
27d50 20 7b 48 31 35 33 31 30 7d 20 20 49 66 20 61 6e   {H15310}  If an
27d60 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
27d70 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d  upt | interrupt]
27d80 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65   or a run-time e
27d90 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rror.**         
27da0 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20    occurs during 
27db0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
27dc0 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a 2a 20 20  e3_step(S)].**  
27dd0 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20 5b           for a [
27de0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27df0 6e 74 5d 20 53 20 63 72 65 61 74 65 64 20 75 73  nt] S created us
27e00 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
27e10 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
27e20 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
27e30 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  are()] or.**    
27e40 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
27e50 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
27e60 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
27e70 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
27e80 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
27e90 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53 51 4c  ITE_ERROR], [SQL
27ea0 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20 5b 53  ITE_BUSY], or [S
27eb0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
27ec0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
27ed0 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
27ee0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27ef0 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
27f00 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
27f10 74 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c  t set {H13770} <
27f20 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65  S10700>.**.** Re
27f30 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
27f40 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68   of values in th
27f50 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
27f60 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e   the result set.
27f70 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
27f80 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 31  S:.**.** {H13771
27f90 7d 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20  }  After a call 
27fa0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
27fb0 28 53 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e  (S)] that return
27fc0 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 0a  s [SQLITE_ROW],.
27fd0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
27fe0 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
27ff0 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65  ount(S)] routine
28000 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
28010 20 73 61 6d 65 20 76 61 6c 75 65 0a 2a 2a 20 20   same value.**  
28020 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20           as the 
28030 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28040 63 6f 75 6e 74 28 53 29 5d 20 66 75 6e 63 74 69  count(S)] functi
28050 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37  on..**.** {H1377
28060 32 7d 20 20 41 66 74 65 72 20 5b 73 71 6c 69 74  2}  After [sqlit
28070 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
28080 72 65 74 75 72 6e 65 64 20 61 6e 79 20 76 61 6c  returned any val
28090 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a  ue other than.**
280a0 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49             [SQLI
280b0 54 45 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72  TE_ROW] or befor
280c0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
280d0 53 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  S)] has been cal
280e0 6c 65 64 20 6f 6e 20 74 68 65 0a 2a 2a 20 20 20  led on the.**   
280f0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
28100 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72  d statement] for
28110 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
28120 73 69 6e 63 65 20 69 74 20 77 61 73 0a 2a 2a 20  since it was.** 
28130 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
28140 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
28150 70 61 72 65 64 5d 20 6f 72 20 5b 73 71 6c 69 74  pared] or [sqlit
28160 65 33 5f 72 65 73 65 74 20 7c 20 72 65 73 65 74  e3_reset | reset
28170 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ],.**           
28180 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  the [sqlite3_dat
28190 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74  a_count(S)] rout
281a0 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
281b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
281c0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
281d0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
281e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
281f0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
28200 61 74 61 74 79 70 65 73 20 7b 48 31 30 32 36 35  atatypes {H10265
28210 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31 32  } <S10110><S1012
28220 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
28230 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
28240 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72 79  * {H10266} Every
28250 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
28260 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
28270 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
28280 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
28290 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
282a0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
282b0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
282c0 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
282d0 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
282e0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
282f0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
28300 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e  ULL.** </ul> {EN
28310 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  D}.**.** These c
28320 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
28330 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
28340 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
28350 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
28360 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
28370 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
28380 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
28390 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
283a0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
283b0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
283c0 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
283d0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
283e0 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
283f0 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
28400 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
28410 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
28420 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
28430 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
28440 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
28450 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
28460 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
28470 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
28480 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
28490 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
284a0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
284b0 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
284c0 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
284d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
284e0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
284f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
28500 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
28510 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
28520 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
28530 20 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d 20   Query {H13800} 
28540 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S10700>.** KEYW
28550 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
28560 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
28570 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
28580 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
28590 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22  esult set query"
285a0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
285b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
285c0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
285d0 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
285e0 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
285f0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
28600 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
28610 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61 73  y.  In every cas
28620 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
28630 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
28640 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
28650 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28660 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
28670 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
28680 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
28690 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
286a0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
286b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
286c0 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
286d0 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
286e0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
286f0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
28700 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
28710 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
28720 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
28730 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c  returned.  The l
28740 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
28750 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
28760 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
28770 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
28780 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
28790 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
287a0 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
287b0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
287c0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
287d0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
287e0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
287f0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
28800 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
28810 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
28820 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
28830 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
28840 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28850 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
28860 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
28870 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
28880 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
28890 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
288a0 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
288b0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
288c0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
288d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
288e0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
288f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28900 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
28910 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
28920 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
28930 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
28940 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
28950 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
28960 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
28970 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
28980 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
28990 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
289a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
289b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
289c0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
289d0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
289e0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
289f0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
28a00 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
28a10 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
28a20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
28a30 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
28a40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
28a50 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
28a60 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
28a70 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
28a80 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
28a90 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
28aa0 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
28ab0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
28ac0 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72  lumn.  The retur
28ad0 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
28ae0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
28af0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
28b00 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
28b10 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
28b20 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
28b30 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
28b40 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
28b50 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
28b60 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
28b70 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
28b80 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
28b90 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
28ba0 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
28bb0 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
28bc0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
28bd0 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
28be0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
28bf0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
28c00 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
28c10 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
28c20 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
28c30 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
28c40 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
28c50 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
28c60 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
28c70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
28c80 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
28c90 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
28ca0 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
28cb0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
28cc0 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
28cd0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
28ce0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
28cf0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
28d00 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66  or string..** If
28d10 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
28d20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
28d30 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
28d40 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
28d50 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
28d60 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
28d70 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
28d80 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
28d90 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  ..** If the resu
28da0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
28db0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
28dc0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
28dd0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
28de0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
28df0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
28e00 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
28e10 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
28e20 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
28e30 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
28e40 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65  t string..** The
28e50 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
28e60 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
28e70 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
28e80 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a  ator at the end.
28e90 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
28ea0 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20  .  For clarity: 
28eb0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
28ec0 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ed is the number
28ed0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
28ee0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
28ef0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
28f00 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
28f10 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
28f20 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
28f30 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
28f40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
28f50 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
28f60 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
28f70 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65  e always zero te
28f80 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72  rminated.  The r
28f90 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
28fa0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
28fb0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
28fc0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
28fd0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
28fe0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73  .** pointer, pos
28ff0 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c  sibly even a NUL
29000 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
29010 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
29020 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f  umn_bytes16() ro
29030 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
29040 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
29050 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75  mn_bytes().** bu
29060 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73  t leaves the res
29070 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e  ult in UTF-16 in
29080 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
29090 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54  er instead of UT
290a0 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f  F-8..** The zero
290b0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e   terminator is n
290c0 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ot included in t
290d0 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a  his count..**.**
290e0 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75   The object retu
290f0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
29100 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
29110 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
29120 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
29130 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
29140 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
29150 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29160 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
29170 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
29180 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
29190 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
291a0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
291b0 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
291c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
291d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
291e0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
291f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
29200 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
29210 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
29220 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
29230 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
29240 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
29250 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
29260 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
29270 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
29280 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
29290 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
292a0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
292b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
292c0 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
292d0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
292e0 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
292f0 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  riate.  For.** e
29300 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
29310 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
29320 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
29330 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
29340 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
29350 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
29360 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
29370 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
29380 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
29390 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
293a0 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c  cally.  The foll
293b0 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
293c0 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
293d0 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
293e0 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
293f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
29400 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
29410 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
29420 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
29430 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
29440 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
29450 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
29460 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
29470 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
29480 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
29490 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
294a0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
294b0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
294c0 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
294d0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
294e0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
294f0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
29500 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
29510 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
29520 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
29530 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
29540 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
29550 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
29560 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
29570 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
29580 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
29590 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
295a0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
295b0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
295c0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
295d0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
295e0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
295f0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
29600 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
29610 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
29620 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
29630 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
29640 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20  vert from float 
29650 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  to integer.** <t
29660 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
29670 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
29680 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
29690 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
296a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
296b0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
296c0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
296d0 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a  s FLOAT->TEXT.**
296e0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
296f0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
29700 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28    <td> Use atoi(
29710 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
29720 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
29730 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61  AT    <td> Use a
29740 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
29750 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
29760 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
29770 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
29780 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
29790 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
297a0 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
297b0 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28  T then use atoi(
297c0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
297d0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
297e0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
297f0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
29800 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  use atof().** <t
29810 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
29820 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
29830 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
29840 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
29850 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
29860 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
29870 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
29880 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
29890 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
298a0 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
298b0 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
298c0 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
298d0 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
298e0 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
298f0 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
29900 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75  s its.** own equ
29910 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  ivalent internal
29920 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
29930 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
29940 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
29950 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
29960 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
29970 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
29980 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
29990 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
299a0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
299b0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
299c0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
299d0 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
299e0 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
299f0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
29a00 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
29a10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29a20 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
29a30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29a40 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
29a50 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
29a60 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
29a70 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
29a80 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
29a90 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
29aa0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
29ab0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
29ac0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
29ad0 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
29ae0 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
29af0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
29b00 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
29b10 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
29b20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
29b30 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
29b40 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
29b50 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
29b60 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
29b70 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
29b80 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
29b90 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
29ba0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29bb0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
29bc0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
29bd0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
29be0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
29bf0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
29c00 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
29c10 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
29c20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
29c30 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
29c40 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
29c50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
29c60 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
29c70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29c80 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
29c90 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
29ca0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
29cb0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
29cc0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
29cd0 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20  .** Conversions 
29ce0 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
29cf0 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
29d00 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
29d10 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
29d20 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
29d30 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
29d40 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
29d50 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
29d60 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
29d70 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
29d80 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20  inter points to 
29d90 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
29da0 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
29db0 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
29dc0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
29dd0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
29de0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
29df0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
29e00 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
29e10 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
29e20 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
29e30 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
29e40 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
29e50 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
29e60 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
29e70 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
29e80 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
29e90 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
29ea0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
29eb0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
29ec0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
29ed0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
29ee0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
29ef0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
29f00 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
29f10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
29f20 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
29f30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29f40 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
29f50 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
29f60 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
29f70 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
29f80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
29f90 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
29fa0 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
29fb0 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
29fc0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
29fd0 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
29fe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
29ff0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
2a000 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2a010 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
2a020 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
2a030 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
2a040 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
2a050 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
2a060 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
2a070 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a080 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
2a090 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
2a0a0 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
2a0b0 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
2a0c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a0d0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2a0e0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2a0f0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
2a100 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a110 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
2a120 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
2a130 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2a140 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
2a150 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
2a160 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2a170 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  ()..**.** The po
2a180 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2a190 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
2a1a0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2a1b0 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
2a1c0 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
2a1d0 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
2a1e0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2a1f0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2a200 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2a210 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
2a220 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  led.  The memory
2a230 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
2a240 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
2a250 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
2a260 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
2a270 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
2a280 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
2a290 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73  s returned.** [s
2a2a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2a2b0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
2a2c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
2a2d0 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
2a2e0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
2a2f0 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79  *.** If a memory
2a300 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2a310 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
2a320 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
2a330 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
2a340 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
2a350 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
2a360 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
2a370 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
2a380 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
2a390 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
2a3a0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2a3b0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
2a3c0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
2a3d0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
2a3e0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
2a3f0 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
2a400 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
2a410 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  EM]..**.** INVAR
2a420 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
2a430 33 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  3803} The [sqlit
2a440 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53  e3_column_blob(S
2a450 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
2a460 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2a470 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
2a480 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
2a490 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2a4a0 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
2a4b0 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
2a4c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a4d0 20 53 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61   S into a BLOB a
2a4e0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2a4f0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  a.**          po
2a500 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e  inter to the con
2a510 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a  verted value..**
2a520 0a 2a 2a 20 7b 48 31 33 38 30 36 7d 20 54 68 65  .** {H13806} The
2a530 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a540 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e 74  _bytes(S,N)] int
2a550 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2a560 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
2a570 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2a580 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  n the BLOB or st
2a590 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20  ring (exclusive 
2a5a0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
2a5b0 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74     zero terminat
2a5c0 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
2a5d0 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
2a5e0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ned by the.**   
2a5f0 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65         most rece
2a600 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2a610 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2a620 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  S,N)] or.**     
2a630 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
2a640 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 2e  lumn_text(S,N)].
2a650 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 39 7d 20  .**.** {H13809} 
2a660 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
2a670 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e 29  umn_bytes16(S,N)
2a680 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2a690 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
2a6a0 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79      number of by
2a6b0 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
2a6c0 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20  g (exclusive of 
2a6d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2a6e0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2a6f0 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74  on the string) t
2a700 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
2a710 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   by the.**      
2a720 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20      most recent 
2a730 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2a740 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53  _column_text16(S
2a750 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ,N)]..**.** {H13
2a760 38 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  812} The [sqlite
2a770 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
2a780 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2a790 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2a7a0 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
2a7b0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2a7c0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2a7d0 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65  sult set for the
2a7e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2a7f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a800 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74  ] S into a float
2a810 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
2a820 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
2a830 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2a840 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a  f that value..**
2a850 0a 2a 2a 20 7b 48 31 33 38 31 35 7d 20 54 68 65  .** {H13815} The
2a860 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a870 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72  _int(S,N)] inter
2a880 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2a890 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
2a8a0 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2a8b0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2a8c0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
2a8d0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2a8e0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2a8f0 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
2a900 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2a910 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
2a920 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 68        returns th
2a930 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20  e lower 32 bits 
2a940 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
2a950 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 38 7d 20  .**.** {H13818} 
2a960 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
2a970 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20  umn_int64(S,N)] 
2a980 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2a990 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2a9a0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
2a9b0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
2a9c0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2a9d0 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  et for the.**   
2a9e0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
2a9f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2aa00 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
2aa10 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
2aa20 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2aa30 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61  ns a copy of tha
2aa40 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
2aa50 20 7b 48 31 33 38 32 31 7d 20 54 68 65 20 5b 73   {H13821} The [s
2aa60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2aa70 78 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  xt(S,N)] interfa
2aa80 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2aa90 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
2aaa0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
2aab0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2aac0 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
2aad0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2aae0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2aaf0 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65  ent] S into a ze
2ab00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2ab10 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F-8.**          
2ab20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2ab30 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2ab40 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2ab50 2a 2a 20 7b 48 31 33 38 32 34 7d 20 54 68 65 20  ** {H13824} The 
2ab60 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2ab70 74 65 78 74 31 36 28 53 2c 4e 29 5d 20 69 6e 74  text16(S,N)] int
2ab80 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2ab90 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2aba0 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
2abb0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
2abc0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2abd0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
2abe0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
2abf0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
2ac00 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2ac10 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
2ac20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
2ac30 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
2ac40 6f 72 64 65 72 20 73 74 72 69 6e 67 20 61 6e 64  order string and
2ac50 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
2ac60 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74       a pointer t
2ac70 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
2ac80 2a 0a 2a 2a 20 7b 48 31 33 38 32 37 7d 20 54 68  *.** {H13827} Th
2ac90 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2aca0 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74  n_type(S,N)] int
2acb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
2acc0 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f  *          one o
2acd0 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c  f [SQLITE_NULL],
2ace0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2acf0 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ], [SQLITE_FLOAT
2ad00 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
2ad10 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72  SQLITE_TEXT], or
2ad20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61   [SQLITE_BLOB] a
2ad30 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
2ad40 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
2ad50 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20  e Nth column in 
2ad60 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
2ad70 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2ad80 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
2ad90 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20    the [prepared 
2ada0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a  statement] S..**
2adb0 0a 2a 2a 20 7b 48 31 33 38 33 30 7d 20 54 68 65  .** {H13830} The
2adc0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2add0 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74  _value(S,N)] int
2ade0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2adf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
2ae00 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70 72  nter to an [unpr
2ae10 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2ae20 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
2ae30 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2ae40 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
2ae50 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
2ae60 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2ae70 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
2ae80 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20    the [prepared 
2ae90 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
2aea0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2aeb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2aec0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2aed0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2aee0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2aef0 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
2af00 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2af10 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2af20 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
2af30 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2af40 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2af50 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
2af60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2af70 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2af80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2af90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2afa0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
2afb0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2afc0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
2afd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2afe0 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
2aff0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2b000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2b010 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b020 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
2b030 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2b040 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
2b050 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2b060 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2b070 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
2b080 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b090 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
2b0a0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
2b0b0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
2b0c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2b0d0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
2b0e0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
2b0f0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2b100 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33  ment Object {H13
2b110 33 30 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33  300} <S70300><S3
2b120 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0100>.**.** The 
2b130 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2b140 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2b150 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
2b160 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2b170 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
2b180 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2b190 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73  executed success
2b1a0 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65  fully or not exe
2b1b0 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68  cuted at all, th
2b1c0 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20  en.** SQLITE_OK 
2b1d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20  is returned. If 
2b1e0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
2b1f0 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65   statement faile
2b200 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72  d then an.** [er
2b210 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78  ror code] or [ex
2b220 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
2b230 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
2b240 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2b250 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
2b260 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
2b270 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ring the executi
2b280 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72  on of the.** [pr
2b290 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b2a0 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75  ].  If the virtu
2b2b0 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e  al machine has n
2b2c0 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  ot.** completed 
2b2d0 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74  execution when t
2b2e0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63  his routine is c
2b2f0 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c  alled, that is l
2b300 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ike.** encounter
2b310 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  ing an error or 
2b320 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  an [sqlite3_inte
2b330 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70  rrupt | interrup
2b340 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74  t]..** Incomplet
2b350 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65  e updates may be
2b360 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64   rolled back and
2b370 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61   transactions ca
2b380 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e  nceled,.** depen
2b390 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63  ding on the circ
2b3a0 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74  umstances, and t
2b3b0 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  he.** [error cod
2b3c0 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c  e] returned will
2b3d0 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   be [SQLITE_ABOR
2b3e0 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  T]..**.** INVARI
2b3f0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  ANTS:.**.** {H11
2b400 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  302} The [sqlite
2b410 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
2b420 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79  nterface destroy
2b430 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2b440 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2b450 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c  ement] S and rel
2b460 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20  eases all.**    
2b470 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64        memory and
2b480 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20   file resources 
2b490 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a  held by that obj
2b4a0 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  ect..**.** {H113
2b4b0 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  04} If the most 
2b4c0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2b4d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2b4e0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
2b4f0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
2b500 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
2b510 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a  rned an error,.*
2b520 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
2b530 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2b540 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68  e(S)] returns th
2b550 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a  at same error..*
2b560 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
2b570 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
2b580 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2b590 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2b5a0 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
2b5b0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
2b5c0 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 33 30 30  {H13330} <S70300
2b5d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2b5e0 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
2b5f0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2b600 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
2b610 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2b620 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
2b630 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
2b640 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
2b650 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
2b660 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
2b670 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
2b680 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
2b690 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
2b6a0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2b6b0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
2b6c0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
2b6d0 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
2b6e0 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
2b6f0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2b700 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
2b710 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
2b720 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54  **.** {H11332} T
2b730 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2b740 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2b750 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
2b760 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b770 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61  S.**          ba
2b780 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
2b790 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
2b7a0 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  am..**.** {H1133
2b7b0 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  4} If the most r
2b7c0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2b7d0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2b7e0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
2b7f0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
2b800 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
2b810 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2b820 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2b830 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ],.**          o
2b840 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
2b850 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
2b860 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
2b870 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20  led on S,.**    
2b880 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69        then [sqli
2b890 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2b8a0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
2b8b0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36  ]..**.** {H11336
2b8c0 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
2b8d0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2b8e0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2b8f0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2b900 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2b910 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
2b920 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
2b930 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  en.**          [
2b940 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2b950 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
2b960 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2b970 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  code]..**.** {H1
2b980 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  1338} The [sqlit
2b990 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2b9a0 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
2b9b0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
2b9c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  s.**          of
2b9d0 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
2b9e0 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
2b9f0 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
2ba00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
2ba10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2ba20 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
2ba30 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2ba40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
2ba50 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
2ba60 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48  SQL Functions {H
2ba70 31 36 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16100} <S20200>.
2ba80 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
2ba90 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2baa0 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59  routines}.** KEY
2bab0 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
2bac0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2bad0 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59  function}.** KEY
2bae0 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
2baf0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2bb00 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
2bb10 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74   These two funct
2bb20 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
2bb30 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e  ly known as "fun
2bb40 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2bb50 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65  outines").** are
2bb60 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
2bb70 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2bb80 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72  gregates or to r
2bb90 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
2bba0 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74  vior.** of exist
2bbb0 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
2bbc0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
2bbd0 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65    The only diffe
2bbe0 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68  rence between th
2bbf0 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74  e.** two is that
2bc00 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2bc10 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20  meter, the name 
2bc20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20  of the (scalar) 
2bc30 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2bc40 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63  ggregate, is enc
2bc50 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f  oded in UTF-8 fo
2bc60 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2bc70 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20  _function() and 
2bc80 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71  UTF-16.** for sq
2bc90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2bca0 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ction16()..**.**
2bcb0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
2bcc0 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
2bcd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bce0 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
2bcf0 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
2bd00 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
2bd10 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  If a single prog
2bd20 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ram uses more th
2bd30 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
2bd40 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e  ** connection in
2bd50 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53  ternally, then S
2bd60 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
2bd70 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76  t be added indiv
2bd80 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61  idually to.** ea
2bd90 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
2bda0 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  ection..**.** Th
2bdb0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2bdc0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
2bdd0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2bde0 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
2bdf0 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
2be00 2e 20 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66  .  The length of
2be10 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
2be20 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
2be30 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a  s, exclusive of.
2be40 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  ** the zero-term
2be50 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68  inator.  Note th
2be60 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67  at the name leng
2be70 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62  th limit is in b
2be80 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61  ytes, not.** cha
2be90 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74  racters.  Any at
2bea0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
2beb0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
2bec0 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
2bed0 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
2bee0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62  [SQLITE_ERROR] b
2bef0 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
2bf00 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70  *.** The third p
2bf10 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
2bf20 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
2bf30 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
2bf40 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
2bf50 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2bf60 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68  ate takes. If th
2bf70 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
2bf80 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
2bf90 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2bfa0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
2bfb0 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
2bfc0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2bfd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72  ..**.** The four
2bfe0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
2bff0 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
2c000 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
2c010 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
2c020 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
2c030 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
2c040 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
2c050 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51  ameters.  Any SQ
2c060 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
2c070 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
2c080 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
2c090 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54  .** work with UT
2c0a0 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
2c0b0 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
2c0c0 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
2c0d0 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
2c0e0 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
2c0f0 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
2c100 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
2c110 49 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f  It is allowed to
2c120 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
2c130 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c140 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
2c150 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2c160 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  6() multiple.** 
2c170 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
2c180 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74  ame function but
2c190 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
2c1a0 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52  values of eTextR
2c1b0 65 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74  ep..** When mult
2c1c0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2c1d0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2c1e0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
2c1f0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
2c200 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
2c210 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
2c220 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
2c230 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
2c240 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
2c250 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
2c260 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
2c270 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
2c280 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78  ot care what tex
2c290 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73  t.** encoding is
2c2a0 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
2c2b0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
2c2c0 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54  should be [SQLIT
2c2d0 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  E_ANY]..**.** Th
2c2e0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
2c2f0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
2c300 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
2c310 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2c320 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
2c330 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
2c340 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
2c350 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
2c360 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a  _user_data()]..*
2c370 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68  *.** The seventh
2c380 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e  , eighth and nin
2c390 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
2c3a0 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
2c3b0 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
2c3c0 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
2c3d0 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
2c3e0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2c3f0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2c400 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
2c410 20 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75   A scalar SQL fu
2c420 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2c430 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2c440 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
2c450 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c  * callback only,
2c460 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73   NULL pointers s
2c470 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
2c480 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
2c490 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
2c4a0 65 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67  eters. An aggreg
2c4b0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2c4c0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
2c4d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
2c4e0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
2c4f0 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75  al and NULL shou
2c500 6c 64 20 62 65 20 70 61 73 73 65 64 20 66 6f 72  ld be passed for
2c510 20 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74   xFunc. To delet
2c520 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
2c530 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2c540 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
2c550 20 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68   NULL for all th
2c560 72 65 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ree function cal
2c570 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74  lbacks..**.** It
2c580 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
2c590 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
2c5a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2c5b0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
2c5c0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
2c5d0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
2c5e0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
2c5f0 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
2c600 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
2c610 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
2c620 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2c630 6f 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20  odings.  SQLite 
2c640 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
2c650 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
2c660 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
2c670 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
2c680 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
2c690 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
2c6a0 2e 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d  .  A function im
2c6b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2c6c0 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
2c6d0 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
2c6e0 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
2c6f0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
2c700 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2c710 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
2c720 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 41 20  gative nArg.  A 
2c730 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2c740 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78  he preferred tex
2c750 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61  t encoding.** ma
2c760 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61  tches the databa
2c770 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61  se encoding is a
2c780 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68   better.** match
2c790 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
2c7a0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
2c7b0 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
2c7c0 2e 20 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f  .  .** A functio
2c7d0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
2c7e0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
2c7f0 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
2c800 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
2c810 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
2c820 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
2c830 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
2c840 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
2c850 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
2c860 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
2c870 2a 2a 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66  **.** Built-in f
2c880 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
2c890 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
2c8a0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
2c8b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
2c8c0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 70  .** The first ap
2c8d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2c8e0 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  d function with 
2c8f0 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65  a given name ove
2c900 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75  rrides all.** bu
2c910 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
2c920 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   in the same [da
2c930 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2c940 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  n] with the same
2c950 20 6e 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71   name..** Subseq
2c960 75 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  uent application
2c970 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2c980 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e  ns of the same n
2c990 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64  ame only overrid
2c9a0 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c  e .** prior appl
2c9b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2c9c0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61  functions that a
2c9d0 72 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63  re an exact matc
2c9e0 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d  h for the.** num
2c9f0 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72  ber of parameter
2ca00 73 20 61 6e 64 20 70 72 65 66 65 72 72 65 64 20  s and preferred 
2ca10 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2ca20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
2ca30 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2ca40 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
2ca50 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
2ca60 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
2ca70 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
2ca80 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
2ca90 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
2caa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2cab0 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
2cac0 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
2cad0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
2cae0 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
2caf0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2cb00 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2cb10 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30  TS:.**.** {H1610
2cb20 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2cb30 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2cb40 36 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65  6(D,X,...)] inte
2cb50 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65 68 61  rface shall beha
2cb60 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ve.**          a
2cb70 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  s [sqlite3_creat
2cb80 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e  e_function(D,X,.
2cb90 2e 2e 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61  ..)] in every wa
2cba0 79 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  y except that it
2cbb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
2cbc0 65 72 70 72 65 74 73 20 74 68 65 20 58 20 61 72  erprets the X ar
2cbd0 67 75 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d 74  gument as zero-t
2cbe0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36  erminated UTF-16
2cbf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 74  .**          nat
2cc00 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
2cc10 6e 73 74 65 61 64 20 6f 66 20 61 73 20 7a 65 72  nstead of as zer
2cc20 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2cc30 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30  -8..**.** {H1610
2cc40 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  6} A successful 
2cc50 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
2cc60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
2cc70 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2cc80 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e  nction(D,X,N,E,.
2cc90 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  ..)] interface s
2cca0 68 61 6c 6c 20 72 65 67 69 73 74 65 72 0a 2a 2a  hall register.**
2ccb0 20 20 20 20 20 20 20 20 20 20 6f 72 20 72 65 70            or rep
2ccc0 6c 61 63 65 73 20 63 61 6c 6c 62 61 63 6b 20 66  laces callback f
2ccd0 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20  unctions in the 
2cce0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ccf0 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20  tion] D.**      
2cd00 20 20 20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c      used to impl
2cd10 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
2cd20 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77  nction named X w
2cd30 69 74 68 20 4e 20 70 61 72 61 6d 65 74 65 72 73  ith N parameters
2cd40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
2cd50 20 68 61 76 69 6e 67 20 61 20 70 72 65 66 65 72   having a prefer
2cd60 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2cd70 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48  g of E..**.** {H
2cd80 31 36 31 30 39 7d 20 41 20 73 75 63 63 65 73 73  16109} A success
2cd90 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2cda0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2cdb0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
2cdc0 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,S,L)].**       
2cdd0 20 20 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65     shall replace
2cde0 20 74 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e   the P, F, S, an
2cdf0 64 20 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  d L values from 
2ce00 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20  any prior calls 
2ce10 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
2ce20 20 74 68 65 20 73 61 6d 65 20 44 2c 20 58 2c 20   the same D, X, 
2ce30 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75 65 73 2e  N, and E values.
2ce40 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 32 7d 20  .**.** {H16112} 
2ce50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2ce60 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2ce70 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
2ce80 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20   shall fail.**  
2ce90 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20 53          if the S
2cea0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65  QL function name
2ceb0 20 58 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   X is.**        
2cec0 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 35    longer than 25
2ced0 35 20 62 79 74 65 73 20 65 78 63 6c 75 73 69 76  5 bytes exclusiv
2cee0 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 65  e of the zero te
2cef0 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
2cf00 7b 48 31 36 31 31 38 7d 20 54 68 65 20 5b 73 71  {H16118} The [sq
2cf10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2cf20 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
2cf30 46 2c 53 2c 4c 29 5d 20 69 6e 74 65 72 66 61 63  F,S,L)] interfac
2cf40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  e.**          sh
2cf50 61 6c 6c 20 66 61 69 6c 20 75 6e 6c 65 73 73 20  all fail unless 
2cf60 65 69 74 68 65 72 20 46 20 69 73 20 4e 55 4c 4c  either F is NULL
2cf70 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65   and S and L are
2cf80 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 0a 2a 2a 2a   non-NULL or.***
2cf90 20 20 20 20 20 20 20 20 20 46 20 69 73 20 6e 6f           F is no
2cfa0 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64  n-NULL and S and
2cfb0 20 4c 20 61 72 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   L are NULL..**.
2cfc0 2a 2a 20 7b 48 31 36 31 32 31 7d 20 54 68 65 20  ** {H16121} The 
2cfd0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2cfe0 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d  function(D,...)]
2cff0 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
2d000 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
2d010 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72  *          error
2d020 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
2d030 5f 42 55 53 59 5d 20 69 66 20 74 68 65 72 65 20  _BUSY] if there 
2d040 65 78 69 73 74 20 5b 70 72 65 70 61 72 65 64 20  exist [prepared 
2d050 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20  statements].**  
2d060 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74          associat
2d070 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
2d080 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d090 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  ] D..**.** {H161
2d0a0 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
2d0b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2d0c0 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74  (D,X,N,...)] int
2d0d0 65 72 66 61 63 65 20 73 68 61 6c 6c 20 66 61 69  erface shall fai
2d0e0 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  l with.**       
2d0f0 20 20 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65     an error code
2d100 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   of [SQLITE_ERRO
2d110 52 5d 20 69 66 20 70 61 72 61 6d 65 74 65 72 20  R] if parameter 
2d120 4e 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20  N is less.**    
2d130 20 20 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72        than -1 or
2d140 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
2d150 37 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 37  7..**.** {H16127
2d160 7d 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d  } When N is non-
2d170 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73  negative, the [s
2d180 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2d190 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e  nction(D,X,N,...
2d1a0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
2d1b0 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72  nterface shall r
2d1c0 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
2d1d0 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  s to be invoked 
2d1e0 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
2d1f0 20 20 20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e      SQL function
2d200 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d  .**          nam
2d210 65 64 20 58 20 77 68 65 6e 20 74 68 65 20 6e 75  ed X when the nu
2d220 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2d230 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  s to the SQL fun
2d240 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ction is.**     
2d250 20 20 20 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a       exactly N..
2d260 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 30 7d 20 57  **.** {H16130} W
2d270 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68 65  hen N is -1, the
2d280 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2d290 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2d2a0 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
2d2b0 20 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c    interface shal
2d2c0 6c 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  l register callb
2d2d0 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b  acks to be invok
2d2e0 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c 0a 2a  ed for the SQL.*
2d2f0 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
2d300 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68  ion named X with
2d310 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
2d320 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
2d330 7b 48 31 36 31 33 33 7d 20 57 68 65 6e 20 63 61  {H16133} When ca
2d340 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2d350 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2d360 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  D,X,N,...)].**  
2d370 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79 20          specify 
2d380 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2d390 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2d3a0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a  same function X.
2d3b0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
2d3c0 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65  when one impleme
2d3d0 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30  ntation has N>=0
2d3e0 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 68   and the other h
2d3f0 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20  as N=(-1).**    
2d400 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c 65 6d        the implem
2d410 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
2d420 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 73 68 61 6c 6c  non-zero N shall
2d430 20 62 65 20 70 72 65 66 65 72 72 65 64 2e 0a 2a   be preferred..*
2d440 2a 0a 2a 2a 20 7b 48 31 36 31 33 36 7d 20 57 68  *.** {H16136} Wh
2d450 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  en calls to [sql
2d460 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2d470 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e  tion(D,X,N,E,...
2d480 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  )].**          s
2d490 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20  pecify multiple 
2d4a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2d4b0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2d4c0 74 69 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20  tion X with.**  
2d4d0 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65          the same
2d4e0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2d4f0 65 6e 74 73 20 4e 20 62 75 74 20 77 69 74 68 20  ents N but with 
2d500 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20  different.**    
2d510 20 20 20 20 20 20 65 6e 63 6f 64 69 6e 67 73 20        encodings 
2d520 45 2c 20 74 68 65 6e 20 74 68 65 20 69 6d 70 6c  E, then the impl
2d530 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 72 65  ementation where
2d540 20 45 20 6d 61 74 63 68 65 73 20 74 68 65 0a 2a   E matches the.*
2d550 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
2d560 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 73 68 61  ase encoding sha
2d570 6c 6c 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a  ll preferred..**
2d580 0a 2a 2a 20 7b 48 31 36 31 33 39 7d 20 46 6f 72  .** {H16139} For
2d590 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 53 51   an aggregate SQ
2d5a0 4c 20 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74  L function creat
2d5b0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
2d5c0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72       [sqlite3_cr
2d5d0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2d5e0 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20  X,N,E,P,0,S,L)] 
2d5f0 74 68 65 20 66 69 6e 61 6c 69 7a 65 72 0a 2a 2a  the finalizer.**
2d600 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
2d610 6f 6e 20 4c 20 73 68 61 6c 6c 20 61 6c 77 61 79  on L shall alway
2d620 73 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 61  s be invoked exa
2d630 63 74 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 65  ctly once if the
2d640 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 65  .**          ste
2d650 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 20  p function S is 
2d660 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
2d670 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20  re times..**.** 
2d680 7b 48 31 36 31 34 32 7d 20 57 68 65 6e 20 53 51  {H16142} When SQ
2d690 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 74  Lite invokes eit
2d6a0 68 65 72 20 74 68 65 20 78 46 75 6e 63 20 6f 72  her the xFunc or
2d6b0 20 78 53 74 65 70 20 66 75 6e 63 74 69 6f 6e 20   xStep function 
2d6c0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  of.**          a
2d6d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2d6e0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2d6f0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 20  on or aggregate 
2d700 63 72 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  created.**      
2d710 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
2d720 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2d730 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )] or [sqlite3_c
2d740 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2d750 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
2d760 20 74 68 65 6e 20 74 68 65 20 61 72 72 61 79 20   then the array 
2d770 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
2d780 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 73 65  e] objects passe
2d790 64 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  d as the.**     
2d7a0 20 20 20 20 20 74 68 69 72 64 20 70 61 72 61 6d       third param
2d7b0 65 74 65 72 20 73 68 61 6c 6c 20 62 65 20 5b 70  eter shall be [p
2d7c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d7d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2d7e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2d7f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2d800 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2d810 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
2d820 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2d830 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2d840 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2d850 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2d860 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2d870 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2d880 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2d890 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2d8a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2d8b0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2d8c0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2d8d0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2d8e0 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
2d8f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2d900 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
2d910 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2d920 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
2d930 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2d940 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2d950 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2d960 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2d970 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d980 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2d990 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2d9a0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2d9b0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2d9c0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2d9d0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2d9e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2d9f0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2da00 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
2da10 6e 67 73 20 7b 48 31 30 32 36 37 7d 20 3c 53 35  ngs {H10267} <S5
2da20 30 32 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a  0200> <H16100>.*
2da30 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2da40 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
2da50 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
2da60 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
2da70 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
2da80 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
2da90 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
2daa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2dab0 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64  8           1.#d
2dac0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2dad0 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64  16LE        2.#d
2dae0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2daf0 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64  16BE        3.#d
2db00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2db10 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
2db20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
2db30 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
2db40 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
2db50 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
2db60 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
2db70 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20  e_function only 
2db80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2db90 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
2dba0 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
2dbb0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2dbc0 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
2dbd0 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
2dbe0 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
2dbf0 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
2dc00 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
2dc10 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
2dc20 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
2dc30 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
2dc40 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
2dc50 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
2dc60 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
2dc70 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
2dc80 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
2dc90 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
2dca0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
2dcb0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
2dcc0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
2dcd0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
2dce0 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20   help encourage 
2dcf0 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a  people to avoid.
2dd00 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66  ** using these f
2dd10 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65  unctions, we are
2dd20 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65   not going to te
2dd30 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79  ll you want they
2dd40 20 64 6f 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44   do..*/.SQLITE_D
2dd50 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2dd60 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2dd70 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
2dd80 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
2dd90 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2dda0 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
2ddb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
2ddc0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2ddd0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
2dde0 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
2ddf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
2de00 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
2de10 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2de20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
2de30 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
2de40 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
2de50 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
2de60 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
2de70 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
2de80 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2de90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
2dea0 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
2deb0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
2dec0 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  t),void*,sqlite3
2ded0 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _int64);../*.** 
2dee0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
2def0 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
2df00 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
2df10 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32  s {H15100} <S202
2df20 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  00>.**.** The C-
2df30 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
2df40 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
2df50 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2df60 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
2df70 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
2df80 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
2df90 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
2dfa0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
2dfb0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
2dfc0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
2dfd0 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
2dfe0 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
2dff0 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
2e000 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
2e010 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
2e020 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e030 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
2e040 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e050 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
2e060 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
2e070 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
2e080 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2e090 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2e0a0 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  es..** The 4th p
2e0b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
2e0c0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
2e0d0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
2e0e0 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
2e0f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e100 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
2e110 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
2e120 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e130 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
2e140 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
2e150 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
2e160 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2e170 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
2e180 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
2e190 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2e1a0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
2e1b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2e1c0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
2e1d0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2e1e0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e1f0 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
2e200 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
2e210 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
2e220 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2e230 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
2e240 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
2e250 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
2e260 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
2e270 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
2e280 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
2e290 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
2e2a0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2e2b0 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
2e2c0 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
2e2d0 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
2e2e0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2e2f0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e300 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
2e310 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
2e320 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
2e330 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
2e340 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
2e350 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2e360 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2e370 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
2e380 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
2e390 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
2e3a0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
2e3b0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
2e3c0 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ine.  The.** sql
2e3d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2e3e0 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
2e3f0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2e400 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
2e410 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
2e420 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
2e430 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
2e440 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
2e450 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  vely..**.** The 
2e460 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
2e470 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74  meric_type() int
2e480 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
2e490 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65  to apply.** nume
2e4a0 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20  ric affinity to 
2e4b0 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73  the value.  This
2e4c0 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61   means that an a
2e4d0 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64  ttempt is.** mad
2e4e0 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  e to convert the
2e4f0 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74   value to an int
2e500 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67  eger or floating
2e510 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73   point.  If.** s
2e520 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  uch a conversion
2e530 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74   is possible wit
2e540 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66  hout loss of inf
2e550 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68  ormation (in oth
2e560 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20  er.** words, if 
2e570 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73  the value is a s
2e580 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73  tring that looks
2e590 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a   like a number).
2e5a0 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76  ** then the conv
2e5b0 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72  ersion is perfor
2e5c0 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  med.  Otherwise 
2e5d0 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  no conversion oc
2e5e0 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51  curs..** The [SQ
2e5f0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2e600 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63  atatype] after c
2e610 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74  onversion is ret
2e620 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65  urned..**.** Ple
2e630 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
2e640 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
2e650 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
2e660 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
2e670 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
2e680 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
2e690 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2e6a0 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
2e6b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e6c0 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
2e6d0 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
2e6e0 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
2e6f0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2e700 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
2e710 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e720 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
2e730 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2e740 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
2e750 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2e760 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
2e770 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
2e780 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2e790 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
2e7a0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
2e7b0 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
2e7c0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
2e7d0 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
2e7e0 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
2e7f0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  NTS:.**.** {H151
2e800 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  03} The [sqlite3
2e810 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20  _value_blob(V)] 
2e820 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2e830 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2e840 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2e850 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2e860 65 63 74 20 56 20 69 6e 74 6f 20 61 20 42 4c 4f  ect V into a BLO
2e870 42 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 20 20  B and then.**   
2e880 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
2e890 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2e8a0 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e  converted value.
2e8b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 7d 20  .**.** {H15106} 
2e8c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2e8d0 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e 74  ue_bytes(V)] int
2e8e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2e8f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
2e900 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2e910 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  n the BLOB or st
2e920 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20  ring (exclusive 
2e930 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
2e940 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74     zero terminat
2e950 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
2e960 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
2e970 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ned by the.**   
2e980 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65         most rece
2e990 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2e9a0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56  te3_value_blob(V
2e9b0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
2e9c0 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65    [sqlite3_value
2e9d0 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a  _text(V)]..**.**
2e9e0 20 7b 48 31 35 31 30 39 7d 20 54 68 65 20 5b 73   {H15109} The [s
2e9f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2ea00 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61  es16(V)] interfa
2ea10 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ce returns the.*
2ea20 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
2ea30 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2ea40 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  e string (exclus
2ea50 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
2ea60 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
2ea70 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
2ea80 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
2ea90 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2eaa0 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
2eab0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2eac0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2ead0 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20  xt16(V)],.**    
2eae0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76        [sqlite3_v
2eaf0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29  alue_text16be(V)
2eb00 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ], or [sqlite3_v
2eb10 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29  alue_text16le(V)
2eb20 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 32  ]..**.** {H15112
2eb30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2eb40 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20  alue_double(V)] 
2eb50 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2eb60 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2eb70 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2eb80 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2eb90 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f  ect V into a flo
2eba0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
2ebb0 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  e and.**        
2ebc0 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
2ebd0 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a   of that value..
2ebe0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d 20 54  **.** {H15115} T
2ebf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2ec00 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66  e_int(V)] interf
2ec10 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2ec20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2ec30 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2ec40 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2ec50 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69  into a 64-bit si
2ec60 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
2ec70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2ec80 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33  urns the lower 3
2ec90 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69  2 bits of that i
2eca0 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nteger..**.** {H
2ecb0 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69  15118} The [sqli
2ecc0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
2ecd0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2ece0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2ecf0 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
2ed00 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2ed10 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
2ed20 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2ed30 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
2ed40 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
2ed50 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e   copy of that in
2ed60 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  teger..**.** {H1
2ed70 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  5121} The [sqlit
2ed80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29  e3_value_text(V)
2ed90 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2eda0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2edb0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2edc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2edd0 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
2ede0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2edf0 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20  TF-8.**         
2ee00 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2ee10 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2ee20 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2ee30 0a 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54 68 65  .** {H15124} The
2ee40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2ee50 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65 72  text16(V)] inter
2ee60 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2ee70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2ee80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ee90 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2eea0 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72   into a zero-ter
2eeb0 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a  minated 2-byte.*
2eec0 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e  *          align
2eed0 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  ed UTF-16 native
2eee0 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20   byte order.**  
2eef0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61          string a
2ef00 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2ef10 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72  nter to that str
2ef20 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  ing..**.** {H151
2ef30 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  27} The [sqlite3
2ef40 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
2ef50 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2ef60 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2ef70 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
2ef80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2ef90 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
2efa0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2efb0 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20   2-byte.**      
2efc0 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d      aligned UTF-
2efd0 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a  16 big-endian.**
2efe0 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
2eff0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2f000 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
2f010 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
2f020 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74  5130} The [sqlit
2f030 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2f040 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
2f050 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2f060 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2f070 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2f080 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2f090 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2f0a0 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
2f0b0 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
2f0c0 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69  F-16 little-endi
2f0d0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
2f0e0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2f0f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2f100 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  hat string..**.*
2f110 2a 20 7b 48 31 35 31 33 33 7d 20 54 68 65 20 5b  * {H15133} The [
2f120 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
2f130 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  pe(V)] interface
2f140 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
2f150 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c       one of [SQL
2f160 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_NULL], [SQLI
2f170 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51  TE_INTEGER], [SQ
2f180 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20  LITE_FLOAT],.** 
2f190 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
2f1a0 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49  _TEXT], or [SQLI
2f1b0 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72  TE_BLOB] as appr
2f1c0 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20  opriate for.**  
2f1d0 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
2f1e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2f1f0 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ct V..**.** {H15
2f200 31 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  136} The [sqlite
2f210 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2f220 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61  type(V)] interfa
2f230 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20  ce converts.**  
2f240 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f          the [pro
2f250 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2f260 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2f270 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69 6e  nto either an in
2f280 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20 20  teger or.**     
2f290 20 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67 20       a floating 
2f2a0 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20 69  point value if i
2f2b0 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74 68  t can do so with
2f2c0 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20  out loss of.**  
2f2d0 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74          informat
2f2e0 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ion, and returns
2f2f0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2f300 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  NULL],.**       
2f310 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47     [SQLITE_INTEG
2f320 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ER], [SQLITE_FLO
2f330 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
2f340 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  T], or.**       
2f350 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d     [SQLITE_BLOB]
2f360 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20   as appropriate 
2f370 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
2f380 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2f390 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2f3a0 6a 65 63 74 20 56 20 61 66 74 65 72 20 74 68 65  ject V after the
2f3b0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74 65   conversion atte
2f3c0 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  mpt..*/.const vo
2f3d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2f3e0 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
2f3f0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2f400 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2f410 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f420 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2f430 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
2f440 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62  e3_value*);.doub
2f450 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
2f460 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2f470 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2f480 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
2f490 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2f4a0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2f4b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
2f4c0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
2f4d0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
2f4e0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
2f4f0 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
2f500 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2f510 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2f520 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c  value_text16(sql
2f530 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2f540 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2f550 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2f560 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2f570 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2f580 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f590 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16be(sqlite3_val
2f5a0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2f5b0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
2f5c0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2f5d0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2f5e0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
2f5f0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
2f600 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f610 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
2f620 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2f630 20 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30   {H16210} <S2020
2f640 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70  0>.**.** The imp
2f650 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
2f660 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2f670 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20  ctions use this 
2f680 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
2f690 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75  ate.** a structu
2f6a0 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  re for storing t
2f6b0 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
2f6c0 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65  * The first time
2f6d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
2f6e0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2f6f0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
2f700 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74  ed for a.** part
2f710 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
2f720 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74  , SQLite allocat
2f730 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d  es nBytes of mem
2f740 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
2f750 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  that.** memory, 
2f760 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2f770 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20  inter to it. On 
2f780 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
2f790 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
2f7a0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
2f7b0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
2f7c0 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
2f7d0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
2f7e0 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  dex,.** the same
2f7f0 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
2f800 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65  ned. The impleme
2f810 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61  ntation of the a
2f820 67 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65  ggregate can use
2f830 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64  .** the returned
2f840 20 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d   buffer to accum
2f850 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ulate data..**.*
2f860 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  * SQLite automat
2f870 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
2f880 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65   allocated buffe
2f890 72 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  r when the aggre
2f8a0 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f  gate.** query co
2f8b0 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
2f8c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2f8d0 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  er should be a c
2f8e0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
2f8f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
2f900 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
2f910 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
2f920 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2f930 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
2f940 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
2f950 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
2f960 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2f970 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
2f980 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
2f990 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2f9a0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
2f9b0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
2f9c0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2f9d0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2f9e0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2f9f0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 31 7d  :.**.** {H16211}
2fa00 20 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63   The first invoc
2fa10 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
2fa20 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2fa30 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a  ext(C,N)] for.**
2fa40 20 20 20 20 20 20 20 20 20 20 61 20 70 61 72 74            a part
2fa50 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20  icular instance 
2fa60 6f 66 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  of an aggregate 
2fa70 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20  function (for a 
2fa80 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20  particular.**   
2fa90 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43         context C
2faa0 29 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  ) causes SQLite 
2fab0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79  to allocate N by
2fac0 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a  tes of memory,.*
2fad0 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
2fae0 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
2faf0 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65   return a pointe
2fb00 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74  r to the allocat
2fb10 65 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a  ed memory..**.**
2fb20 20 7b 48 31 36 32 31 33 7d 20 49 66 20 61 20 6d   {H16213} If a m
2fb30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2fb40 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
2fb50 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
2fb60 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2fb70 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2fb80 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74  ] then the funct
2fb90 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  ion returns 0..*
2fba0 2a 0a 2a 2a 20 7b 48 31 36 32 31 35 7d 20 53 65  *.** {H16215} Se
2fbb0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
2fbc0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ent invocations 
2fbd0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  of.**          [
2fbe0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2fbf0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20  e_context(C,N)] 
2fc00 66 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e  for the same con
2fc10 74 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a  text pointer C.*
2fc20 2a 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72  *          ignor
2fc30 65 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  e the N paramete
2fc40 72 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70  r and return a p
2fc50 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61  ointer to the sa
2fc60 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  me.**          b
2fc70 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72  lock of memory r
2fc80 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66  eturned by the f
2fc90 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  irst invocation.
2fca0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 37 7d 20  .**.** {H16217} 
2fcb0 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
2fcc0 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
2fcd0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2fce0 78 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20  xt(C,N)] is.**  
2fcf0 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69          automati
2fd00 63 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74  cally freed on t
2fd10 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20  he next call to 
2fd20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2fd30 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
2fd40 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2fd50 7a 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70  ze()] for the [p
2fd60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fd70 74 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a  t] containing.**
2fd80 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67            the ag
2fd90 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
2fda0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2fdb0 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76   context C..*/.v
2fdc0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
2fdd0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
2fde0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2fdf0 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
2fe00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
2fe10 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
2fe20 63 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20  ctions {H16240} 
2fe30 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
2fe40 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
2fe50 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
2fe60 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2fe70 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
2fe80 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
2fe90 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
2fea0 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
2feb0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
2fec0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2fed0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
2fee0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
2fef0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2ff00 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
2ff10 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
2ff20 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
2ff30 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
2ff40 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d   function. {END}
2ff50 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2ff60 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2ff70 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2ff80 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2ff90 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2ffa0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2ffb0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2ffc0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2ffd0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34 33  S:.**.** {H16243
2ffe0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  } The [sqlite3_u
2fff0 73 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74  ser_data(C)] int
30000 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
30010 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
30020 20 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74           P point
30030 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  er from the [sql
30040 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
30050 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
30060 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,S,L)].**       
30070 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
30080 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
30090 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
300a0 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20  )] call that.** 
300b0 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
300c0 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  red the SQL func
300d0 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
300e0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f  with [sqlite3_co
300f0 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69  ntext] C..*/.voi
30100 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
30110 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
30120 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
30130 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
30140 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
30150 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32   Functions {H162
30160 35 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 30  50} <S60600><S20
30170 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  200>.**.** The s
30180 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
30190 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
301a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
301b0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
301c0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
301d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
301e0 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
301f0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
30200 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
30210 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
30220 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
30230 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
30240 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
30250 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
30260 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
30270 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
30280 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
30290 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
302a0 2a 2a 20 7b 48 31 36 32 35 33 7d 20 54 68 65 20  ** {H16253} The 
302b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
302c0 5f 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69  _db_handle(C)] i
302d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
302e0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
302f0 2a 20 20 20 20 20 20 20 20 20 20 44 20 70 6f 69  *          D poi
30300 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73  nter from the [s
30310 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30320 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
30330 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20  ,F,S,L)].**     
30340 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
30350 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30360 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  16(D,X,N,E,P,F,S
30370 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a  ,L)] call that.*
30380 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
30390 74 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75  tered the SQL fu
303a0 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65  nction associate
303b0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
303c0 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73  context] C..*/.s
303d0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
303e0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
303f0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
30400 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
30410 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
30420 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48  uxiliary Data {H
30430 31 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16270} <S20200>.
30440 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
30450 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
30460 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
30470 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
30480 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
30490 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
304a0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
304b0 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
304c0 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
304d0 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
304e0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
304f0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
30500 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
30510 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
30520 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
30530 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
30540 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
30550 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
30560 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
30570 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
30580 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
30590 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
305a0 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
305b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
305c0 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
305d0 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
305e0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
305f0 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
30600 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
30610 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
30620 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
30630 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
30640 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
30650 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
30660 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
30670 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
30680 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
30690 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
306a0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
306b0 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
306c0 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
306d0 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
306e0 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
306f0 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
30700 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
30710 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
30720 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
30730 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
30740 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
30750 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
30760 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
30770 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
30780 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
30790 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
307a0 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
307b0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
307c0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66  ned function. If
307d0 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73   no metadata has
307e0 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65   been ever.** be
307f0 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e  en set for the N
30800 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  th argument of t
30810 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20  he function, or 
30820 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  if the correspon
30830 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ding.** function
30840 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63   parameter has c
30850 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65  hanged since the
30860 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73   meta-data was s
30870 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  et,.** then sqli
30880 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
30890 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
308a0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
308b0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
308c0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
308d0 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
308e0 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
308f0 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
30900 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
30910 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
30920 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
30930 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
30940 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
30950 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
30960 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
30970 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
30980 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
30990 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
309a0 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
309b0 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
309c0 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e  * If it is not N
309d0 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
309e0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
309f0 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
30a00 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
30a10 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
30a20 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
30a30 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
30a40 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
30a50 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
30a60 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
30a70 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
30a80 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
30a90 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
30aa0 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
30ab0 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
30ac0 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
30ad0 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
30ae0 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
30af0 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
30b00 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
30b10 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
30b20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f  any time.  The o
30b30 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73  nly guarantee is
30b40 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73   that.** the des
30b50 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
30b60 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
30b70 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72  e metadata is dr
30b80 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  opped..**.** In 
30b90 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
30ba0 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
30bb0 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
30bc0 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78   calls for.** ex
30bd0 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61  pressions that a
30be0 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63  re constant at c
30bf0 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69  ompile time. Thi
30c00 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72  s includes liter
30c10 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
30c20 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a   SQL variables..
30c30 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
30c40 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
30c50 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
30c60 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
30c70 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
30c80 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
30c90 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
30ca0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37  TS:.**.** {H1627
30cb0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
30cc0 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29  get_auxdata(C,N)
30cd0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
30ce0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
30cf0 20 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74            to met
30d00 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
30d10 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 70 61   with the Nth pa
30d20 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53  rameter of the S
30d30 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  QL function.**  
30d40 20 20 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f          whose co
30d50 6e 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e  ntext is C, or N
30d60 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20  ULL if there is 
30d70 6e 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  no metadata asso
30d80 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  ciated.**       
30d90 20 20 20 77 69 74 68 20 74 68 61 74 20 70 61 72     with that par
30da0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ameter..**.** {H
30db0 31 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69  16274} The [sqli
30dc0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
30dd0 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66  C,N,P,D)] interf
30de0 61 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65  ace assigns a me
30df0 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20  tadata.**       
30e00 20 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20     pointer P to 
30e10 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65  the Nth paramete
30e20 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  r of the SQL fun
30e30 63 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65  ction with conte
30e40 78 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  xt C..**.** {H16
30e50 32 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  276} SQLite will
30e60 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
30e70 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20  ructor D with a 
30e80 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a  single argument.
30e90 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 63  **          whic
30ea0 68 20 69 73 20 74 68 65 20 6d 65 74 61 64 61 74  h is the metadat
30eb0 61 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c  a pointer P foll
30ec0 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a  owing a call to.
30ed0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
30ee0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
30ef0 28 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20  (C,N,P,D)] when 
30f00 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f  SQLite ceases to
30f10 20 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20   hold.**        
30f20 20 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a    the metadata..
30f30 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 37 7d 20 53  **.** {H16277} S
30f40 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20  QLite ceases to 
30f50 68 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f  hold metadata fo
30f60 72 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  r an SQL functio
30f70 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  n parameter.**  
30f80 20 20 20 20 20 20 20 20 77 68 65 6e 20 74 68 65          when the
30f90 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70   value of that p
30fa0 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
30fb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 38 7d  ..**.** {H16278}
30fc0 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   When [sqlite3_s
30fd0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
30fe0 2c 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c  ,D)] is invoked,
30ff0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
31000 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63  **          is c
31010 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72  alled for any pr
31020 69 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73 73  ior metadata ass
31030 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
31040 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a   same function.*
31050 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65  *          conte
31060 78 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74  xt C and paramet
31070 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  er N..**.** {H16
31080 32 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  279} SQLite will
31090 20 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72   call destructor
310a0 73 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61  s for any metada
310b0 74 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67  ta it is holding
310c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
310d0 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72  a particular [pr
310e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
310f0 5d 20 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a  ] S when either.
31100 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
31110 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f  ite3_reset(S)] o
31120 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
31130 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65  ize(S)] is calle
31140 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  d..*/.void *sqli
31150 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
31160 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31170 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
31180 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
31190 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
311a0 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
311b0 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
311c0 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
311d0 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
311e0 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
311f0 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
31200 61 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c  avior {H10280} <
31210 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30100>.**.** Th
31220 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
31230 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
31240 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
31250 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
31260 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
31270 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
31280 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
31290 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
312a0 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  If the destructo
312b0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
312c0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
312d0 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
312e0 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65  e content pointe
312f0 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a  r is constant.**
31300 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20   and will never 
31310 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73  change.  It does
31320 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
31330 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 0a  destroyed.  The.
31340 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
31350 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
31360 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
31370 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
31380 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
31390 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
313a0 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
313b0 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
313c0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
313d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
313e0 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
313f0 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
31400 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
31410 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
31420 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
31430 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
31440 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  s.  See ticket #
31450 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  2191..*/.typedef
31460 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
31470 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
31480 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
31490 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
314a0 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
314b0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
314c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
314d0 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
314e0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
314f0 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
31500 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
31510 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
31520 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
31530 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32 30   {H16400} <S2020
31540 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
31550 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
31560 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
31570 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
31580 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
31590 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
315a0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
315b0 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
315c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
315d0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
315e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
315f0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
31600 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
31610 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
31620 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
31630 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
31640 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
31650 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
31660 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
31670 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
31680 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
31690 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
316a0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
316b0 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
316c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
316d0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
316e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
316f0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
31700 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31710 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
31720 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
31730 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
31740 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31750 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
31760 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
31770 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
31780 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
31790 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
317a0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
317b0 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
317c0 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
317d0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
317e0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
317f0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
31800 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
31810 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
31820 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
31830 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31840 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
31850 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
31860 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
31870 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
31880 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
31890 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
318a0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
318b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
318c0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
318d0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
318e0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
318f0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
31900 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
31910 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
31920 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
31930 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
31940 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
31950 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
31960 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
31970 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
31980 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75  ult_error16() fu
31990 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65  nctions.** cause
319a0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64   the implemented
319b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
319c0 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74   throw an except
319d0 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75  ion..** SQLite u
319e0 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
319f0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
31a00 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
31a10 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
31a20 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
31a30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31a40 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
31a50 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
31a60 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c  or message.  SQL
31a70 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
31a80 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
31a90 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
31aa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31ab0 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
31ac0 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72   SQLite.** inter
31ad0 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67  prets the string
31ae0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
31af0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61  sult_error16() a
31b00 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  s UTF-16 in nati
31b10 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72  ve.** byte order
31b20 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20  .  If the third 
31b30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
31b40 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31b50 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
31b60 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31b70 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
31b80 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
31b90 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
31ba0 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
31bb0 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
31bc0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
31bd0 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65  acter..** If the
31be0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
31bf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
31c00 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
31c10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31c20 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
31c30 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
31c40 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
31c50 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
31c60 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
31c70 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
31c80 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
31c90 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
31ca0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31cb0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
31cc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31cd0 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
31ce0 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
31cf0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
31d00 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
31d10 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
31d20 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
31d30 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
31d40 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
31d50 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
31d60 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
31d70 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
31d80 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68  hout harm..** Th
31d90 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31da0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
31db0 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
31dc0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
31dd0 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
31de0 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
31df0 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
31e00 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64   function.  By d
31e10 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
31e20 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
31e30 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75  ITE_ERROR.  A su
31e40 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
31e50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31e60 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
31e70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31e80 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
31e90 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
31ea0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
31eb0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
31ec0 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
31ed0 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
31ee0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
31ef0 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
31f00 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
31f10 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
31f20 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72   to long to repr
31f30 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  esent..**.** The
31f40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31f50 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
31f60 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
31f70 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
31f80 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
31f90 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
31fa0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
31fb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
31fc0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
31fd0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
31fe0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
31ff0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
32000 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32010 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
32020 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
32030 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
32040 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
32050 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
32060 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
32070 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
32080 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
32090 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
320a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
320b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
320c0 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
320d0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
320e0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
320f0 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
32100 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nt..**.** The sq
32110 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
32120 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  l() interface se
32130 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
32140 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
32150 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32160 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
32170 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
32180 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32190 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f  text(), sqlite3_
321a0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c  result_text16(),
321b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
321c0 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61  lt_text16le(), a
321d0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
321e0 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74  t_text16be() int
321f0 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74  erfaces.** set t
32200 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
32210 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
32220 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32230 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74  ion to be.** a t
32240 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68  ext string which
32250 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20   is represented 
32260 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  as UTF-8, UTF-16
32270 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
32280 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  er,.** UTF-16 li
32290 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle endian, or 
322a0 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61  UTF-16 big endia
322b0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
322c0 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73  .** SQLite takes
322d0 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
322e0 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
322f0 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
32300 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
32310 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
32320 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
32330 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68  rfaces..** If th
32340 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
32350 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
32360 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
32370 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
32380 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
32390 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
323a0 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
323b0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
323c0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
323d0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
323e0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
323f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
32400 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32410 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
32420 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
32430 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
32440 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
32450 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
32460 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
32470 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
32480 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
32490 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
324a0 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
324b0 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a  unction result..
324c0 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61  ** If the 4th pa
324d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
324e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
324f0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
32500 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
32510 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
32520 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
32530 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
32540 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
32550 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
32560 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
32570 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
32580 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
32590 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
325a0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66  at result..** If
325b0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
325c0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
325d0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
325e0 6e 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20  nterfaces or.** 
325f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
32600 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
32610 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
32620 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20  TE_STATIC, then 
32630 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65  SQLite.** assume
32640 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
32650 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69  or BLOB result i
32660 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70  s in constant sp
32670 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
32680 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74 20  .** copy the it 
32690 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75  or call a destru
326a0 63 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61 73  ctor when it has
326b0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
326c0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
326d0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
326e0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
326f0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
32700 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
32710 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
32720 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
32730 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
32740 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
32750 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
32760 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
32770 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
32780 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
32790 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
327a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
327b0 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
327c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
327d0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
327e0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
327f0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
32800 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32810 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
32820 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
32830 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
32840 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32850 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
32860 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
32870 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a  rameter.  The.**
32880 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32890 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
328a0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
328b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
328c0 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
328d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
328e0 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
328f0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
32900 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
32910 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
32920 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
32930 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
32940 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
32950 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74  m..** A [protect
32960 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32970 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
32980 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
32990 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
329a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
329b0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
329c0 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
329d0 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
329e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
329f0 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
32a00 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
32a10 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
32a20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
32a30 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
32a40 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
32a50 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
32a60 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
32a70 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
32a80 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32a90 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
32aa0 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
32ab0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
32ac0 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
32ad0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
32ae0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
32af0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 33 7d  :.**.** {H16403}
32b00 20 54 68 65 20 64 65 66 61 75 6c 74 20 72 65 74   The default ret
32b10 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 61  urn value from a
32b20 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ny SQL function 
32b30 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  is NULL..**.** {
32b40 48 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71 6c  H16406} The [sql
32b50 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
32b60 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
32b70 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
32b80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
32b90 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
32ba0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 20  ction C to be a 
32bb0 42 4c 4f 42 20 74 68 61 74 20 69 73 20 4e 20 62  BLOB that is N b
32bc0 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ytes.**         
32bd0 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20 77   in length and w
32be0 69 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  ith content poin
32bf0 74 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a  ted to by V..**.
32c00 2a 2a 20 7b 48 31 36 34 30 39 7d 20 54 68 65 20  ** {H16409} The 
32c10 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32c20 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74  double(C,V)] int
32c30 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
32c40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
32c50 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
32c60 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
32c70 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
32c80 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  nt value V..**.*
32c90 2a 20 7b 48 31 36 34 31 32 7d 20 54 68 65 20 5b  * {H16412} The [
32ca0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32cb0 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74  rror(C,V,N)] int
32cc0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
32cd0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
32ce0 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66        value of f
32cf0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
32d00 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
32d10 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  h error code.** 
32d20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
32d30 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54  _ERROR] and a UT
32d40 46 2d 38 20 65 72 72 6f 72 20 6d 65 73 73 61 67  F-8 error messag
32d50 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20  e copied from V 
32d60 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  up to the.**    
32d70 20 20 20 20 20 20 66 69 72 73 74 20 7a 65 72 6f        first zero
32d80 20 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e   byte or until N
32d90 20 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20   bytes are read 
32da0 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  if N is positive
32db0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 35 7d  ..**.** {H16415}
32dc0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
32dd0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c 56  sult_error16(C,V
32de0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
32df0 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
32e00 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
32e10 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
32e20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
32e30 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
32e40 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
32e50 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
32e60 61 6e 64 20 61 20 55 54 46 2d 31 36 20 6e 61 74  and a UTF-16 nat
32e70 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 65  ive byte order e
32e80 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20  rror message.** 
32e90 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 64 20           copied 
32ea0 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65  from V up to the
32eb0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
32ec0 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20  inator or until 
32ed0 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20  N bytes.**      
32ee0 20 20 20 20 61 72 65 20 72 65 61 64 20 69 66 20      are read if 
32ef0 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a  N is positive..*
32f00 2a 0a 2a 2a 20 7b 48 31 36 34 31 38 7d 20 54 68  *.** {H16418} Th
32f10 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
32f20 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43  t_error_toobig(C
32f30 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
32f40 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a  nges the return.
32f50 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
32f60 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
32f70 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
32f80 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
32f90 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
32fa0 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49     [SQLITE_TOOBI
32fb0 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70  G] and an approp
32fc0 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73  riate error mess
32fd0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  age..**.** {H164
32fe0 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  21} The [sqlite3
32ff0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
33000 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61 63  mem(C)] interfac
33010 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65  e changes the re
33020 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  turn.**         
33030 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75   value of the fu
33040 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
33050 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
33060 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
33070 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
33080 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70  NOMEM] and an ap
33090 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
330a0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b  message..**.** {
330b0 48 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71 6c  H16424} The [sql
330c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
330d0 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74  r_code(C,E)] int
330e0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
330f0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
33100 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74        value of t
33110 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  he function C to
33120 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
33130 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
33140 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   E..**          
33150 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  The error messag
33160 65 20 74 65 78 74 20 69 73 20 75 6e 63 68 61 6e  e text is unchan
33170 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ged..**.** {H164
33180 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  27} The [sqlite3
33190 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29  _result_int(C,V)
331a0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
331b0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
331c0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
331d0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
331e0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
331f0 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e  integer value V.
33200 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 30 7d 20  .**.** {H16430} 
33210 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
33220 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20  ult_int64(C,V)] 
33230 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
33240 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
33250 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
33260 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
33270 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 69 6e  be the 64-bit in
33280 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a  teger value V..*
33290 2a 0a 2a 2a 20 7b 48 31 36 34 33 33 7d 20 54 68  *.** {H16433} Th
332a0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
332b0 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72  t_null(C)] inter
332c0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
332d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
332e0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
332f0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55  ction C to be NU
33300 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33  LL..**.** {H1643
33310 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  6} The [sqlite3_
33320 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c  result_text(C,V,
33330 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,D)] interface 
33340 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
33350 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
33360 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
33370 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46   C to be the UTF
33380 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  -8 string.**    
33390 20 20 20 20 20 20 56 20 75 70 20 74 6f 20 74 68        V up to th
333a0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
333b0 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
333c0 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
333d0 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
333e0 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  f V if N is non-
333f0 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
33400 7b 48 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71  {H16439} The [sq
33410 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33420 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  t16(C,V,N,D)] in
33430 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
33440 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
33450 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
33460 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
33470 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69   the UTF-16 nati
33480 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
33490 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
334a0 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
334b0 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20  st zero if N is 
334c0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
334d0 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73       or the firs
334e0 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69  t N bytes of V i
334f0 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
33500 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ive..**.** {H164
33510 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  42} The [sqlite3
33520 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
33530 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
33540 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
33550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
33560 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
33570 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
33580 65 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64  e UTF-16 big-end
33590 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ian.**          
335a0 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74  string V up to t
335b0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66  he first zero if
335c0 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   N is negative.*
335d0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
335e0 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20  e first N bytes 
335f0 6f 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e  or V if N is non
33600 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a  -negative..**.**
33610 20 7b 48 31 36 34 34 35 7d 20 54 68 65 20 5b 73   {H16445} The [s
33620 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33630 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
33640 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
33650 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
33660 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
33670 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
33680 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 6c   be the UTF-16 l
33690 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20  ittle-endian.** 
336a0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
336b0 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
336c0 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e  t zero if N is n
336d0 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
336e0 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74      or the first
336f0 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
33700 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
33710 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34  ve..**.** {H1644
33720 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
33730 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56  result_value(C,V
33740 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
33750 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
33760 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
33770 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
33780 74 6f 20 62 65 20 74 68 65 20 5b 75 6e 70 72 6f  to be the [unpro
33790 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
337a0 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20  alue].**        
337b0 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a    object V..**.*
337c0 2a 20 7b 48 31 36 34 35 31 7d 20 54 68 65 20 5b  * {H16451} The [
337d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
337e0 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e  eroblob(C,N)] in
337f0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
33800 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
33810 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
33820 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
33830 20 61 6e 20 4e 2d 62 79 74 65 20 42 4c 4f 42 20   an N-byte BLOB 
33840 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a  of all zeros..**
33850 0a 2a 2a 20 7b 48 31 36 34 35 34 7d 20 54 68 65  .** {H16454} The
33860 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
33870 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73  _error()] and [s
33880 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33890 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  ror16()].**     
338a0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
338b0 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
338c0 68 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73 61  heir error messa
338d0 67 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f 72  ge strings befor
338e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
338f0 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  turning..**.** {
33900 48 31 36 34 35 37 7d 20 49 66 20 74 68 65 20 44  H16457} If the D
33910 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61   destructor para
33920 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
33930 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
33940 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
33950 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
33960 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
33970 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  D)], [sqlite3_re
33980 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
33990 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
339a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
339b0 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
339c0 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  N,D)], or.**    
339d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
339e0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
339f0 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20  ,V,N,D)] is the 
33a00 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45  constant [SQLITE
33a10 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20  _STATIC].**     
33a20 20 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65 73       then no des
33a30 74 72 75 63 74 6f 72 20 69 73 20 65 76 65 72 20  tructor is ever 
33a40 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f  called on the po
33a50 69 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c 69  inter V and SQLi
33a60 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
33a70 73 73 75 6d 65 73 20 74 68 61 74 20 56 20 69 73  ssumes that V is
33a80 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a   immutable..**.*
33a90 2a 20 7b 48 31 36 34 36 30 7d 20 49 66 20 74 68  * {H16460} If th
33aa0 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70  e D destructor p
33ab0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
33ac0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
33ad0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
33ae0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
33af0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
33b00 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ,N,D)], [sqlite3
33b10 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
33b20 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
33b30 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
33b40 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43  esult_text16be(C
33b50 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,N,D)], or.** 
33b60 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
33b70 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
33b80 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74  e(C,V,N,D)] is t
33b90 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20  he constant.**  
33ba0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
33bb0 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20  TRANSIENT] then 
33bc0 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  the interfaces m
33bd0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
33be0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
33bf0 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20  ontent of V and 
33c00 72 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79  retains the copy
33c10 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 33 7d  ..**.** {H16463}
33c20 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75   If the D destru
33c30 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74  ctor parameter t
33c40 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
33c50 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d  t_blob(C,V,N,D)]
33c60 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
33c70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33c80 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73  xt(C,V,N,D)], [s
33c90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33ca0 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  xt16(C,V,N,D)],.
33cb0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
33cc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33cd0 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20  16be(C,V,N,D)], 
33ce0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
33cf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33d00 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29  ext16le(C,V,N,D)
33d10 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20  ] is some value 
33d20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  other than.**   
33d30 20 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73 74         the const
33d40 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54 41  ants [SQLITE_STA
33d50 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  TIC] and [SQLITE
33d60 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e  _TRANSIENT] then
33d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
33d80 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
33d90 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44  the destructor D
33da0 20 77 69 74 68 20 56 20 61 73 20 69 74 73 20 6f   with V as its o
33db0 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  nly argument.** 
33dc0 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 69 74           when it
33dd0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
33de0 74 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a  th the V value..
33df0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
33e00 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
33e10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
33e20 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
33e30 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
33e40 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33e50 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
33e60 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
33e70 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
33e80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33e90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33ea0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
33eb0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
33ec0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
33ed0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
33ee0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
33ef0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
33f00 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33f10 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
33f20 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
33f30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33f40 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
33f50 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
33f60 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33f70 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
33f80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
33f90 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
33fa0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
33fb0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
33fc0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
33fd0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
33fe0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33ff0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
34000 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
34010 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
34020 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
34030 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34040 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
34050 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
34060 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
34070 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
34080 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34090 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
340a0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
340b0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
340c0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
340d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
340e0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
340f0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
34100 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
34110 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
34120 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34130 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
34140 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
34150 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
34160 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
34170 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
34180 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
34190 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
341a0 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73  _value*);.void s
341b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
341c0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
341d0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
341e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
341f0 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
34200 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
34210 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33 30   {H16600} <S2030
34220 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  0>.**.** These f
34230 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65  unctions are use
34240 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c  d to add new col
34250 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
34260 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   to the.** [data
34270 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34280 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
34290 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
342a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
342b0 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c   of the new coll
342c0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69  ation sequence i
342d0 73 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61  s specified as a
342e0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
342f0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
34300 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
34310 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61  and sqlite3_crea
34320 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
34330 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31  ).** and a UTF-1
34340 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c  6 string for sql
34350 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34360 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c  ation16(). In al
34370 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e  l cases.** the n
34380 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73  ame is passed as
34390 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
343a0 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
343b0 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  *.** The third a
343c0 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f  rgument may be o
343d0 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
343e0 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  nts [SQLITE_UTF8
343f0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  ],.** [SQLITE_UT
34400 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54  F16LE] or [SQLIT
34410 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69  E_UTF16BE], indi
34420 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20  cating that the 
34430 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  user-supplied.**
34440 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
34450 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f   to be passed po
34460 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
34470 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  s encoded using 
34480 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36  UTF-8,.** UTF-16
34490 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20   little-endian, 
344a0 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  or UTF-16 big-en
344b0 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
344c0 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ly. The.** third
344d0 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20   argument might 
344e0 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f  also be [SQLITE_
344f0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74  UTF16_ALIGNED] t
34500 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a  o indicate that.
34510 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65  ** the routine e
34520 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20  xpects pointers 
34530 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61  to 16-bit word a
34540 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a  ligned strings.*
34550 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74  * of UTF-16 in t
34560 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
34570 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
34580 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a   computer..**.**
34590 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
345a0 65 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20  e user supplied 
345b0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
345c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
345d0 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  fth.** argument.
345e0 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c    If it is NULL,
345f0 20 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d   this is the sam
34600 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68  e as deleting th
34610 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
34620 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74  equence (so that
34630 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63   SQLite cannot c
34640 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e  all it anymore).
34650 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68  .** Each time th
34660 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75  e application su
34670 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20  pplied function 
34680 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69  is invoked, it i
34690 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69  s passed.** as i
346a0 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ts first paramet
346b0 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  er a copy of the
346c0 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73   void* passed as
346d0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
346e0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
346f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34700 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
34710 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34720 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  n16()..**.** The
34730 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d   remaining argum
34740 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c  ents to the appl
34750 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
34760 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f   routine are two
34770 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63   strings,.** eac
34780 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  h represented by
34790 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61   a (length, data
347a0 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64  ) pair and encod
347b0 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69  ed in the encodi
347c0 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70  ng.** that was p
347d0 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
347e0 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e  rd argument when
347f0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   the collation s
34800 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72  equence was.** r
34810 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d  egistered. {END}
34820 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
34830 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  n defined collat
34840 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  ion routine shou
34850 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67  ld.** return neg
34860 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70  ative, zero or p
34870 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66  ositive if the f
34880 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c  irst string is l
34890 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75  ess than,.** equ
348a0 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
348b0 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
348c0 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28  d string. i.e. (
348d0 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47  STRING1 - STRING
348e0 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  2)..**.** The sq
348f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34900 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
34910 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
34920 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
34930 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
34940 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74   it takes an ext
34950 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ra argument whic
34960 68 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  h is a destructo
34970 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c  r for.** the col
34980 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73  lation.  The des
34990 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
349a0 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61  d when the colla
349b0 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72  tion is.** destr
349c0 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73  oyed and is pass
349d0 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ed a copy of the
349e0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
349f0 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a  r void* pointer.
34a00 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
34a10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34a20 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c  on_v2()..** Coll
34a30 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72  ations are destr
34a40 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61  oyed when they a
34a50 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  re overridden by
34a60 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20   later calls to 
34a70 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e  the.** collation
34a80 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69   creation functi
34a90 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ons or when the 
34aa0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34ab0 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a  tion] is closed.
34ac0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
34ad0 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a  3_close()]..**.*
34ae0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
34af0 0a 2a 2a 20 7b 48 31 36 36 30 33 7d 20 41 20 73  .** {H16603} A s
34b00 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
34b10 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
34b20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
34b30 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
34b40 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74  ,X,E,P,F,D)] int
34b50 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  erface.**       
34b60 20 20 20 72 65 67 69 73 74 65 72 73 20 66 75 6e     registers fun
34b70 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63  ction F as the c
34b80 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
34b90 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20  on used to.**   
34ba0 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74         implement
34bb0 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20   collation X on 
34bc0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
34bd0 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a  nnection] B for.
34be0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
34bf0 62 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63  bases having enc
34c00 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b  oding E..**.** {
34c10 48 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75  H16604} SQLite u
34c20 6e 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 58  nderstands the X
34c30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
34c40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
34c50 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34c60 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
34c70 2c 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74  ,D)] as a zero-t
34c80 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20  erminated.**    
34c90 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69        UTF-8 stri
34ca0 6e 67 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  ng in which case
34cb0 20 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20   is ignored for 
34cc0 41 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73  ASCII characters
34cd0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
34ce0 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20   is significant 
34cf0 66 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68  for non-ASCII ch
34d00 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
34d10 7b 48 31 36 36 30 36 7d 20 53 75 63 63 65 73 73  {H16606} Success
34d20 69 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ive calls to [sq
34d30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34d40 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c  lation_v2(B,X,E,
34d50 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20  P,F,D)].**      
34d60 20 20 20 20 77 69 74 68 20 74 68 65 20 73 61 6d      with the sam
34d70 65 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20  e values for B, 
34d80 58 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69  X, and E, overri
34d90 64 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a  de prior values.
34da0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50  **          of P
34db0 2c 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a  , F, and D..**.*
34dc0 2a 20 7b 48 31 36 36 30 39 7d 20 49 66 20 74 68  * {H16609} If th
34dd0 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 69  e destructor D i
34de0 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  n [sqlite3_creat
34df0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
34e00 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20  ,X,E,P,F,D)].** 
34e10 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20           is not 
34e20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73 20  NULL then it is 
34e30 63 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67 75  called with argu
34e40 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65 0a  ment P when the.
34e50 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
34e60 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
34e70 73 20 64 72 6f 70 70 65 64 20 62 79 20 53 51 4c  s dropped by SQL
34e80 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  ite..**.** {H166
34e90 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  12} A collating 
34ea0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
34eb0 70 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 6f  ped when it is o
34ec0 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a  verloaded..**.**
34ed0 20 7b 48 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c   {H16615} A coll
34ee0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
34ef0 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 74  s dropped when t
34f00 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
34f10 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
34f20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69     is closed usi
34f30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
34f40 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  e()]..**.** {H16
34f50 36 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65 72  618} The pointer
34f60 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63   P in [sqlite3_c
34f70 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
34f80 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
34f90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
34fa0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
34fb0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
34fc0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6d  meter to the com
34fd0 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20  parison.**      
34fe0 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 66      function F f
34ff0 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  or all subsequen
35000 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  t invocations of
35010 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32   F..**.** {H1662
35020 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  1} A call to [sq
35030 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
35040 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46  lation(B,X,E,P,F
35050 29 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a  )] is exactly.**
35060 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
35070 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f 20  me as a call to 
35080 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35090 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20  collation_v2()] 
350a0 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
350b0 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65   the same parame
350c0 74 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20  ters and a NULL 
350d0 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a  destructor..**.*
350e0 2a 20 7b 48 31 36 36 32 34 7d 20 46 6f 6c 6c 6f  * {H16624} Follo
350f0 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33 5f  wing a [sqlite3_
35100 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35110 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
35120 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ],.**          S
35130 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 63  QLite uses the c
35140 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
35150 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65 78  on F for all tex
35160 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20  t comparison.** 
35170 20 20 20 20 20 20 20 20 20 6f 70 65 72 61 74 69           operati
35180 6f 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  ons on the [data
35190 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
351a0 20 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65   B on text value
351b0 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  s that.**       
351c0 20 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61     use the colla
351d0 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61  ting sequence na
351e0 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  med X..**.** {H1
351f0 36 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  6627} The [sqlit
35200 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35210 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29  ion16(B,X,E,P,F)
35220 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  ] works the same
35230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20  .**          as 
35240 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35250 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c  collation(B,X,E,
35260 50 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68 61  P,F)] except tha
35270 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
35280 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65    collation name
35290 20 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64   X is understood
352a0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
352b0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
352c0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 74  **          inst
352d0 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a  ead of UTF-8..**
352e0 0a 2a 2a 20 7b 48 31 36 36 33 30 7d 20 57 68 65  .** {H16630} Whe
352f0 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61  n multiple compa
35300 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  rison functions 
35310 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f  are available fo
35320 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  r the same.**   
35330 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67         collating
35340 20 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74   sequence, SQLit
35350 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e  e chooses the on
35360 65 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63  e whose text enc
35370 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  oding.**        
35380 20 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c    requires the l
35390 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63  east amount of c
353a0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74  onversion from t
353b0 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20  he default.**   
353c0 20 20 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f         text enco
353d0 64 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ding of the data
353e0 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  base..*/.int sql
353f0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35400 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
35410 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
35420 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
35430 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
35440 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
35450 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
35460 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
35470 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
35480 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
35490 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
354a0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
354b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
354c0 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
354d0 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
354e0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
354f0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
35500 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
35510 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
35520 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
35530 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
35540 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
35550 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
35560 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
35570 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
35580 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
35590 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
355a0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
355b0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
355c0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
355d0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
355e0 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
355f0 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c 53  acks {H16700} <S
35600 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20  20300>.**.** To 
35610 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
35620 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
35630 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
35640 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
35650 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
35660 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
35670 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
35680 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
35690 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74  with the.** [dat
356a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
356b0 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77  ] to be called w
356c0 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
356d0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
356e0 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
356f0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  quired..**.** If
35700 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
35710 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
35720 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
35730 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
35740 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74   API,.** then it
35750 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e   is passed the n
35760 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65  ames of undefine
35770 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
35780 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73  ences as strings
35790 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55  .** encoded in U
357a0 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20 49  TF-8. {H16703} I
357b0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  f sqlite3_collat
357c0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69  ion_needed16() i
357d0 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e  s used,.** the n
357e0 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20  ames are passed 
357f0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63  as UTF-16 in mac
35800 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65  hine native byte
35810 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c   order..** A cal
35820 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
35830 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e  tion replaces an
35840 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62  y existing callb
35850 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ack..**.** When 
35860 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
35870 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
35880 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
35890 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
358a0 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
358b0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
358c0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
358d0 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
358e0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
358f0 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65  ded16().  The se
35900 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
35910 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
35920 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
35930 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
35940 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
35950 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
35960 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f  E_UTF16BE],.** o
35970 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
35980 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
35990 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
359a0 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
359b0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
359c0 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
359d0 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72  uired.  The four
359e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
359f0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
35a00 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
35a10 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a  ation sequence..
35a20 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
35a30 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ck function shou
35a40 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20  ld register the 
35a50 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  desired collatio
35a60 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
35a70 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35a80 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
35a90 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
35aa0 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
35ab0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35ac0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  ollation_v2()]..
35ad0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
35ae0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 32 7d  :.**.** {H16702}
35af0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
35b00 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
35b10 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
35b20 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20  D,P,F)].**      
35b30 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
35b40 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
35b50 31 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73 65  16(D,P,F)] cause
35b60 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
35b70 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35b80 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76  ection] D to inv
35b90 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77  oke callback F w
35ba0 69 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20 20  ith first.**    
35bb0 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20        parameter 
35bc0 50 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e 65  P whenever it ne
35bd0 65 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e  eds a comparison
35be0 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a   function for a.
35bf0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
35c00 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 74  ating sequence t
35c10 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
35c20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a  know about..**.*
35c30 2a 20 7b 48 31 36 37 30 34 7d 20 45 61 63 68 20  * {H16704} Each 
35c40 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
35c50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  to [sqlite3_coll
35c60 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
35c70 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
35c80 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
35c90 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76  n_needed16()] ov
35ca0 65 72 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c  errides the call
35cb0 62 61 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a  back registered.
35cc0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74  **          on t
35cd0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
35ce0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79  e connection] by
35cf0 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20   prior calls to 
35d00 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
35d10 20 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a     interface..**
35d20 0a 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54 68 65  .** {H16706} The
35d30 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65 71   name of the req
35d40 75 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67  uested collating
35d50 20 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65 64   function passed
35d60 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
35d70 20 20 20 20 34 74 68 20 70 61 72 61 6d 65 74 65      4th paramete
35d80 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
35d90 6b 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66  k is in UTF-8 if
35da0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
35db0 20 20 20 20 20 20 20 20 20 20 77 61 73 20 72 65            was re
35dc0 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b  gistered using [
35dd0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
35de0 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 0a  n_needed()] and.
35df0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69  **          is i
35e00 6e 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  n UTF-16 native 
35e10 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 74 68  byte order if th
35e20 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a  e callback was.*
35e30 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
35e40 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  tered using [sql
35e50 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
35e60 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69  eeded16()]..*/.i
35e70 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
35e80 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73  tion_needed(.  s
35e90 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
35ea0 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  *, .  void(*)(vo
35eb0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
35ec0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
35ed0 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  char*).);.int sq
35ee0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
35ef0 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
35f00 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
35f10 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
35f20 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
35f30 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
35f40 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  *).);../*.** Spe
35f50 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
35f60 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
35f70 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
35f80 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
35f90 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
35fa0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
35fb0 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
35fc0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
35fd0 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
35fe0 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
35ff0 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
36000 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
36010 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  */.int sqlite3_k
36020 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
36030 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
36040 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
36050 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
36060 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
36070 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
36080 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
36090 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67  .);../*.** Chang
360a0 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20  e the key on an 
360b0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20  open database.  
360c0 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  If the current d
360d0 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a  atabase is not.*
360e0 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69  * encrypted, thi
360f0 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65  s routine will e
36100 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70  ncrypt it.  If p
36110 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d  New==0 or nNew==
36120 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  0, the.** databa
36130 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e  se is decrypted.
36140 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
36150 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
36160 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
36170 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
36180 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
36190 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
361a0 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28  t sqlite3_rekey(
361b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
361c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
361d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
361e0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
361f0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
36200 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
36210 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
36220 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
36230 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78  3REF: Suspend Ex
36240 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
36250 6f 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33 30  ort Time {H10530
36260 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a  } <S40410>.**.**
36270 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65   The sqlite3_sle
36280 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61  ep() function ca
36290 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74  uses the current
362a0 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65   thread to suspe
362b0 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20  nd execution.** 
362c0 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e  for at least a n
362d0 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
362e0 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
362f0 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
36300 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f  ..**.** If the o
36310 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
36320 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
36330 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
36340 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  with.** millisec
36350 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
36360 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
36370 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
36380 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20  ed up to.** the 
36390 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
363a0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  The number of mi
363b0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
363c0 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  eep actually.** 
363d0 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74  requested from t
363e0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
363f0 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  tem is returned.
36400 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
36410 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
36420 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
36430 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
36440 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
36450 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
36460 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
36470 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
36480 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 33 7d 20  .**.** {H10533} 
36490 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65  The [sqlite3_sle
364a0 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65  ep(M)] interface
364b0 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c   invokes the xSl
364c0 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  eep.**          
364d0 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
364e0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
364f0 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  fs|VFS] in order
36500 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
36510 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f  suspend executio
36520 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
36530 20 74 68 72 65 61 64 20 66 6f 72 20 61 74 20 6c   thread for at l
36540 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  east.**         
36550 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e   M milliseconds.
36560 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 36 7d 20  .**.** {H10536} 
36570 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65  The [sqlite3_sle
36580 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65  ep(M)] interface
36590 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
365a0 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ber of.**       
365b0 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20     milliseconds 
365c0 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c  of sleep actuall
365d0 79 20 72 65 71 75 65 73 74 65 64 20 6f 66 20 74  y requested of t
365e0 68 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20  he operating.** 
365f0 20 20 20 20 20 20 20 20 20 73 79 73 74 65 6d 2c           system,
36600 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
36610 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
36620 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a  parameter M..*/.
36630 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  int sqlite3_slee
36640 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  p(int);../*.** C
36650 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
36660 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
36670 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69  ing Temporary Fi
36680 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32  les {H10310} <S2
36690 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  0000>.**.** If t
366a0 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
366b0 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
366c0 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
366d0 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
366e0 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
366f0 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74  r (a.k.a. direct
36700 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
36710 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
36720 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
36730 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  ite will be plac
36740 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
36750 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76  tory.  If this v
36760 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20  ariable.** is a 
36770 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
36780 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72  en SQLite perfor
36790 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  ms a search for 
367a0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a  an appropriate.*
367b0 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
367c0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
367d0 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
367e0 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20   to modify this 
367f0 76 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20  variable once a 
36800 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36810 74 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20 62 65 65  tion].** has bee
36820 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73  n opened.  It is
36830 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
36840 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
36850 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
36860 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
36870 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
36880 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
36890 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
368a0 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
368b0 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d  een call and rem
368c0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68  ain unchanged th
368d0 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c  ereafter..*/.SQL
368e0 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
368f0 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
36900 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
36910 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
36920 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
36930 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36  ode {H12930} <S6
36940 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0200>.** KEYWORD
36950 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
36960 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ode}.**.** The s
36970 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
36980 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
36990 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
369a0 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66  ro or.** zero if
369b0 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62   the given datab
369c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
369d0 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
369e0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a  utocommit mode,.
369f0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
36a00 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64    Autocommit mod
36a10 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
36a20 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69  lt..** Autocommi
36a30 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
36a40 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
36a50 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75  statement..** Au
36a60 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
36a70 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61   re-enabled by a
36a80 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
36a90 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
36aa0 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
36ab0 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
36ac0 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
36ad0 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
36ae0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
36af0 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69  action (errors i
36b00 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
36b10 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
36b20 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  IOERR],.** [SQLI
36b30 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49  TE_NOMEM], [SQLI
36b40 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53  TE_BUSY], and [S
36b50 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
36b60 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72  ) then the.** tr
36b70 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20  ansaction might 
36b80 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
36b90 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
36ba0 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a  he only way to.*
36bb0 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68  * find out wheth
36bc0 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  er SQLite automa
36bd0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
36be0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
36bf0 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20  ion after.** an 
36c00 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20  error is to use 
36c10 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
36c20 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
36c30 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 31 7d 20  .**.** {H12931} 
36c40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  The [sqlite3_get
36c50 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20  _autocommit(D)] 
36c60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36c70 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a  s non-zero or.**
36c80 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 69            zero i
36c90 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
36ca0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73  connection] D is
36cb0 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
36cc0 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20  tocommit.**     
36cd0 20 20 20 20 20 6d 6f 64 65 2c 20 72 65 73 70 65       mode, respe
36ce0 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b  ctively..**.** {
36cf0 48 31 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d  H12932} Autocomm
36d00 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
36d10 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
36d20 7b 48 31 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d  {H12933} Autocom
36d30 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61  mit mode is disa
36d40 62 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73  bled by a succes
36d50 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61  sful [BEGIN] sta
36d60 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tement..**.** {H
36d70 31 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69  12934} Autocommi
36d80 74 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  t mode is enable
36d90 64 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75  d by a successfu
36da0 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  l [COMMIT] or [R
36db0 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20  OLLBACK].**     
36dc0 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a       statement..
36dd0 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
36de0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 39 33 36  S:.**.** {A12936
36df0 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  } If another thr
36e00 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20  ead changes the 
36e10 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75  autocommit statu
36e20 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  s of the databas
36e30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
36e40 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
36e50 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72  his routine is r
36e60 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  unning, then the
36e70 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
36e80 20 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 64            is und
36e90 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
36ea0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
36eb0 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b  ommit(sqlite3*);
36ec0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36ed0 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62  : Find The Datab
36ee0 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
36ef0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
36f00 6e 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36 30  nt {H13120} <S60
36f10 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  600>.**.** The s
36f20 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
36f30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
36f40 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ns the [database
36f50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
36f60 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20  dle.** to which 
36f70 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
36f80 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20  ement] belongs. 
36f90 20 54 68 65 20 64 61 74 61 62 61 73 65 20 68 61   The database ha
36fa0 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62 79  ndle returned by
36fb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 68  .** sqlite3_db_h
36fc0 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d  andle is the sam
36fd0 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
36fe0 65 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66  e that was the f
36ff0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
37000 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
37010 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63  _prepare_v2()] c
37020 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69  all (or its vari
37030 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75  ants) that was u
37040 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65  sed to.** create
37050 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
37060 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
37070 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
37080 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31  NTS:.**.** {H131
37090 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  23} The [sqlite3
370a0 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69  _db_handle(S)] i
370b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
370c0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
370d0 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 5b 64         to the [d
370e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
370f0 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  on] associated w
37100 69 74 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ith the.**      
37110 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
37120 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73  atement] S..*/.s
37130 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
37140 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
37150 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
37160 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
37170 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65  the next prepare
37180 64 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  d statement {H13
37190 31 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a  140} <S60600>.**
371a0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
371b0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
371c0 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74  nter to the next
371d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
371e0 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70  ment] after.** p
371f0 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20  Stmt associated 
37200 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
37210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
37220 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73  Db.  If pStmt is
37230 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68   NULL.** then th
37240 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
37250 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
37260 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70  o the first prep
37270 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
37280 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
37290 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  h the database c
372a0 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20  onnection pDb.  
372b0 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73  If no prepared s
372c0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69  tatement.** sati
372d0 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74  sfies the condit
372e0 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75  ions of this rou
372f0 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73  tine, it returns
37300 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   NULL..**.** INV
37310 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
37320 48 31 33 31 34 33 7d 20 49 66 20 44 20 69 73 20  H13143} If D is 
37330 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
37340 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c  ection] that hol
37350 64 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ds one or more.*
37360 2a 20 20 20 20 20 20 20 20 20 20 75 6e 66 69 6e  *          unfin
37370 61 6c 69 7a 65 64 20 5b 70 72 65 70 61 72 65 64  alized [prepared
37380 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64   statements] and
37390 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   S is a NULL poi
373a0 6e 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20  nter,.**        
373b0 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
373c0 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d  next_stmt(D, S)]
373d0 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72   routine shall r
373e0 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a  eturn a pointer.
373f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6f  **          to o
37400 6e 65 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  ne of the prepar
37410 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  ed statements as
37420 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 44 2e  sociated with D.
37430 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 36 7d 20  .**.** {H13146} 
37440 49 66 20 44 20 69 73 20 61 20 5b 64 61 74 61 62  If D is a [datab
37450 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37460 74 68 61 74 20 68 6f 6c 64 73 20 6e 6f 20 75 6e  that holds no un
37470 66 69 6e 61 6c 69 7a 65 64 0a 2a 2a 20 20 20 20  finalized.**    
37480 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
37490 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20  statements] and 
374a0 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
374b0 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  ter, then.**    
374c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e        [sqlite3_n
374d0 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20  ext_stmt(D, S)] 
374e0 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65  routine shall re
374f0 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  turn a NULL poin
37500 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31  ter..**.** {H131
37510 34 39 7d 20 49 66 20 53 20 69 73 20 61 20 5b 70  49} If S is a [p
37520 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
37530 74 5d 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62  t] in the [datab
37540 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37550 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  D.**          an
37560 64 20 53 20 69 73 20 6e 6f 74 20 74 68 65 20 6c  d S is not the l
37570 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ast prepared sta
37580 74 65 6d 65 6e 74 20 69 6e 20 44 2c 20 74 68 65  tement in D, the
37590 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  n.**          [s
375a0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
375b0 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20  (D, S)] routine 
375c0 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70  shall return a p
375d0 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ointer.**       
375e0 20 20 20 74 6f 20 74 68 65 20 6e 65 78 74 20 70     to the next p
375f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
37600 74 20 69 6e 20 44 20 61 66 74 65 72 20 53 2e 0a  t in D after S..
37610 2a 2a 0a 2a 2a 20 7b 48 31 33 31 35 32 7d 20 49  **.** {H13152} I
37620 66 20 53 20 69 73 20 74 68 65 20 6c 61 73 74 20  f S is the last 
37630 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
37640 65 6e 74 5d 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ent] in the.**  
37650 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
37660 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
37670 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
37680 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53  3_next_stmt(D, S
37690 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  )].**          r
376a0 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74  outine shall ret
376b0 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  urn a NULL point
376c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  er..**.** ASSUMP
376d0 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
376e0 33 31 35 34 7d 20 54 68 65 20 5b 64 61 74 61 62  3154} The [datab
376f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37700 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
37710 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  all to.**       
37720 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74     [sqlite3_next
37730 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74  _stmt(D,S)] must
37740 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65   refer to an ope
37750 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20  n database.**   
37760 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f         connectio
37770 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75  n and in particu
37780 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  lar must not be 
37790 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
377a0 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  */.sqlite3_stmt 
377b0 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  *sqlite3_next_st
377c0 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c  mt(sqlite3 *pDb,
377d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70   sqlite3_stmt *p
377e0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
377f0 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41  PI3REF: Commit A
37800 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69  nd Rollback Noti
37810 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
37820 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36 30  ks {H12950} <S60
37830 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  400>.**.** The s
37840 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
37850 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
37860 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
37870 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
37880 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
37890 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
378a0 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65  tion is committe
378b0 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61  d..** Any callba
378c0 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
378d0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
378e0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
378f0 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
37900 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
37910 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
37920 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  dden..** The sql
37930 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
37940 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
37950 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
37960 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
37970 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
37980 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63  enever a transac
37990 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65  tion is committe
379a0 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61  d..** Any callba
379b0 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
379c0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
379d0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
379e0 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
379f0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
37a00 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
37a10 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72  dden..** The pAr
37a20 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61  g argument is pa
37a30 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ssed through to 
37a40 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
37a50 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
37a60 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f   on a commit hoo
37a70 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  k function retur
37a80 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20  ns non-zero,.** 
37a90 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
37aa0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
37ab0 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
37ac0 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66  .** If another f
37ad0 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76  unction was prev
37ae0 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
37af0 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76  d, its.** pArg v
37b00 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
37b10 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c  .  Otherwise NUL
37b20 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  L is returned..*
37b30 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
37b40 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
37b50 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
37b60 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
37b70 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
37b80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37b90 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
37ba0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e  he callback.  An
37bb0 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
37bc0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
37bd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
37be0 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
37bf0 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
37c00 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
37c10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
37c20 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
37c30 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f  triggered the co
37c40 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62  mmit.** or rollb
37c50 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20  ack hook in the 
37c60 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20  first place..** 
37c70 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
37c80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
37c90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
37ca0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
37cb0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
37cc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
37cd0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
37ce0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
37cf0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
37d00 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67  *.** Registering
37d10 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
37d20 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
37d30 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f  llback..**.** Fo
37d40 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
37d50 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72  f this API, a tr
37d60 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69  ansaction is sai
37d70 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a  d to have been.*
37d80 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66  * rolled back if
37d90 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f   an explicit "RO
37da0 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e  LLBACK" statemen
37db0 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f  t is executed, o
37dc0 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72  r.** an error or
37dd0 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73   constraint caus
37de0 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72  es an implicit r
37df0 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72  ollback to occur
37e00 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63  ..** The rollbac
37e10 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
37e20 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
37e30 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
37e40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
37e50 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
37e60 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
37e70 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
37e80 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c  osed..** The rol
37e90 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
37ea0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
37eb0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
37ec0 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  s.** rolled back
37ed0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69   because a commi
37ee0 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  t callback retur
37ef0 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a  ned non-zero..**
37f00 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e   <todo> Check on
37f10 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a   this </todo>.**
37f20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
37f30 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 31 7d 20 54  **.** {H12951} T
37f40 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
37f50 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  it_hook(D,F,P)] 
37f60 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
37f70 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ers the.**      
37f80 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e      callback fun
37f90 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e  ction F to be in
37fa0 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d  voked with argum
37fb0 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a  ent P whenever.*
37fc0 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61  *          a tra
37fd0 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73  nsaction commits
37fe0 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
37ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
38000 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 32 7d 20  .**.** {H12952} 
38010 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d  The [sqlite3_com
38020 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  mit_hook(D,F,P)]
38030 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
38040 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e  ns the P argumen
38050 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  t.**          fr
38060 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  om the previous 
38070 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61  call with the sa
38080 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
38090 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20  nection] D,.**  
380a0 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20          or NULL 
380b0 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  on the first cal
380c0 6c 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  l for a particul
380d0 61 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ar database conn
380e0 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  ection D..**.** 
380f0 7b 48 31 32 39 35 33 7d 20 45 61 63 68 20 63 61  {H12953} Each ca
38100 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
38110 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76  ommit_hook()] ov
38120 65 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c  erwrites the cal
38130 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20  lback.**        
38140 20 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20    registered by 
38150 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a  prior calls..**.
38160 2a 2a 20 7b 48 31 32 39 35 34 7d 20 49 66 20 74  ** {H12954} If t
38170 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f  he F argument to
38180 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
38190 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73  _hook(D,F,P)] is
381a0 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
381b0 20 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69    then the commi
381c0 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  t hook callback 
381d0 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20  is canceled and 
381e0 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20  no callback.**  
381f0 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b          is invok
38200 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61  ed when a transa
38210 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a  ction commits..*
38220 2a 0a 2a 2a 20 7b 48 31 32 39 35 35 7d 20 49 66  *.** {H12955} If
38230 20 74 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c   the commit call
38240 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
38250 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 63  -zero then the c
38260 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20 20  ommit is.**     
38270 20 20 20 20 20 63 6f 6e 76 65 72 74 65 64 20 69       converted i
38280 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
38290 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 31 7d 20 54  **.** {H12961} T
382a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  he [sqlite3_roll
382b0 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  back_hook(D,F,P)
382c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
382d0 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20  sters the.**    
382e0 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66        callback f
382f0 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20  unction F to be 
38300 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
38310 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
38320 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74  .**          a t
38330 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73  ransaction rolls
38340 20 62 61 63 6b 20 6f 6e 20 74 68 65 20 5b 64 61   back on the [da
38350 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38360 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  n] D..**.** {H12
38370 39 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  962} The [sqlite
38380 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
38390 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  D,F,P)] interfac
383a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 0a  e returns the P.
383b0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75  **          argu
383c0 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
383d0 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68  evious call with
383e0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
383f0 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
38400 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f  connection] D, o
38410 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69  r NULL on the fi
38420 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  rst call.**     
38430 20 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69       for a parti
38440 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 63  cular database c
38450 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a  onnection D..**.
38460 2a 2a 20 7b 48 31 32 39 36 33 7d 20 45 61 63 68  ** {H12963} Each
38470 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
38480 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
38490 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68  )] overwrites th
384a0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
384b0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
384c0 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  d by prior calls
384d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 34 7d  ..**.** {H12964}
384e0 20 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65   If the F argume
384f0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  nt to [sqlite3_r
38500 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46  ollback_hook(D,F
38510 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  ,P)] is NULL.** 
38520 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68           then th
38530 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  e rollback hook 
38540 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63  callback is canc
38550 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c  eled and no call
38560 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
38570 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
38580 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72   a transaction r
38590 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f  olls back..*/.vo
385a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  id *sqlite3_comm
385b0 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  it_hook(sqlite3*
385c0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
385d0 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73   void*);.void *s
385e0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
385f0 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76  hook(sqlite3*, v
38600 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20  oid(*)(void *), 
38610 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
38620 41 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68  API3REF: Data Ch
38630 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f  ange Notificatio
38640 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32  n Callbacks {H12
38650 39 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a  970} <S60400>.**
38660 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
38670 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e  update_hook() in
38680 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
38690 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
386a0 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
386b0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
386c0 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69  ection] identifi
386d0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
386e0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62  argument.** to b
386f0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
38700 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61  er a row is upda
38710 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
38720 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79   deleted..** Any
38730 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
38740 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
38750 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
38760 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  n.** for the sam
38770 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
38780 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
38790 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  den..**.** The s
387a0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
387b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
387c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69  he function to i
387d0 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20  nvoke when a.** 
387e0 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
387f0 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
38800 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ted..** The firs
38810 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
38820 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  e callback is a 
38830 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
38840 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
38850 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
38860 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73  hook()..** The s
38870 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61  econd callback a
38880 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
38890 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  f [SQLITE_INSERT
388a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  ], [SQLITE_DELET
388b0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
388c0 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e  E_UPDATE], depen
38