/ Hex Artifact Content
Login

Artifact f4392dc19920dd45077d3aafd3a14024cca85176:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69   $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 34 33 30 20 32 30 30 39 2f 30  n,v 1.430 2009/0
05f0: 32 2f 31 31 20 31 35 3a 30 34 3a 34 30 20 64 72  2/11 15:04:40 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20  .** These no-op 
0750: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
0760: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65  in front of inte
0770: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74  rfaces to mark t
0780: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hose.** interfac
0790: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70  es as either dep
07a0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72  recated or exper
07b0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70  imental.  New ap
07c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
07d0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70  ould not use dep
07e0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65  recated intrface
07f0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
0800: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72  port for backwar
0810: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
0820: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
0830: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
0840: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
0850: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
0860: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
0870: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0880: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0890: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
08a0: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
08b0: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
08c0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
08d0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
08e0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
08f0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0900: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0910: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
0920: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
0930: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
0940: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
0950: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
0960: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
0970: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0980: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0990: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
09a0: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
09b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
09c0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
09d0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
09e0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
09f0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a00: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a10: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0a20: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0a30: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0a40: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0a50: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0a60: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0a70: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0a80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0a90: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0aa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0ab0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0ac0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0ad0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0ae0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31  n Numbers {H1001
0af0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
0b00: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0b10: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f  SION and SQLITE_
0b20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23  VERSION_NUMBER #
0b30: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68  defines in.** th
0b40: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65  e sqlite3.h file
0b50: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72   specify the ver
0b60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77  sion of SQLite w
0b70: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61  ith which.** tha
0b80: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73  t header file is
0b90: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a   associated..**.
0ba0: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22  ** The "version"
0bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20   of SQLite is a 
0bc0: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f  string of the fo
0bd0: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54  rm "X.Y.Z"..** T
0be0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61  he phrase "alpha
0bf0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68  " or "beta" migh
0c00: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66  t be appended af
0c10: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68  ter the Z..** Th
0c20: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a  e X value is maj
0c30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0c40: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51  r always 3 in SQ
0c50: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20  Lite3..** The X 
0c60: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0c70: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64  es when backward
0c80: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
0c90: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64  is.** broken and
0ca0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65   we intend to ne
0cb0: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61  ver break backwa
0cc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0cd0: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75  y..** The Y valu
0ce0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  e is the minor v
0cf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
0d00: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  d only changes w
0d10: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65  hen.** there are
0d20: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65   major feature e
0d30: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74  nhancements that
0d40: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f   are forwards co
0d50: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20  mpatible.** but 
0d60: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f  not backwards co
0d70: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  mpatible..** The
0d80: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20   Z value is the 
0d90: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61  release number a
0da0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  nd is incremente
0db0: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0dc0: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0dd0: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0de0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d  ever Y is increm
0df0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ented..**.** See
0e00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
0e10: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  libversion()] an
0e20: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  d [sqlite3_libve
0e30: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e  rsion_number()].
0e40: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
0e50: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31  S:.**.** {H10011
0e60: 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  } The SQLITE_VER
0e70: 53 49 4f 4e 20 23 64 65 66 69 6e 65 20 69 6e 20  SION #define in 
0e80: 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65  the sqlite3.h he
0e90: 61 64 65 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a  ader file shall.
0ea0: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 76 61 6c  **          eval
0eb0: 75 61 74 65 20 74 6f 20 61 20 73 74 72 69 6e 67  uate to a string
0ec0: 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73   literal that is
0ed0: 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73   the SQLite vers
0ee0: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
0ef0: 77 69 74 68 20 77 68 69 63 68 20 74 68 65 20 68  with which the h
0f00: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73  eader file is as
0f10: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  sociated..**.** 
0f20: 7b 48 31 30 30 31 34 7d 20 54 68 65 20 53 51 4c  {H10014} The SQL
0f30: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0f40: 45 52 20 23 64 65 66 69 6e 65 20 73 68 61 6c 6c  ER #define shall
0f50: 20 72 65 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69   resolve to an i
0f60: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
0f70: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75     with the valu
0f80: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0f90: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0fa0: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20   X, Y, and Z.** 
0fb0: 20 20 20 20 20 20 20 20 20 61 72 65 20 74 68 65           are the
0fc0: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20   major version, 
0fd0: 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61  minor version, a
0fe0: 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  nd release numbe
0ff0: 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  r..*/.#define SQ
1000: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1010: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
1020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1030: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d  ERSION_NUMBER  -
1040: 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d  -VERSION-NUMBER-
1050: 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  -../*.** CAPI3RE
1060: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
1070: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
1080: 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c 53 36  ers {H10020} <S6
1090: 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0100>.** KEYWORD
10a0: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
10b0: 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  on.**.** These f
10c0: 65 61 74 75 72 65 73 20 70 72 6f 76 69 64 65 20  eatures provide 
10d0: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
10e0: 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c  tion as the [SQL
10f0: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20  ITE_VERSION].** 
1100: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  and [SQLITE_VERS
1110: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66  ION_NUMBER] #def
1120: 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61 64  ines in the head
1130: 65 72 2c 20 62 75 74 20 61 72 65 20 61 73 73 6f  er, but are asso
1140: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
1150: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1160: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
1170: 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75 73   file.  Cautious
1180: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
1190: 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20  ht.** include a 
11a0: 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72 20 61  check in their a
11b0: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 76 65  pplication to ve
11c0: 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c  rify that.** sql
11d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
11e0: 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 73 20  number() always 
11f0: 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1200: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  e.** [SQLITE_VER
1210: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a  SION_NUMBER]..**
1220: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1230: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1240: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1250: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1260: 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74  on as is.** in t
1270: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
1280: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1290: 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e 63 74  tant.  The funct
12a0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 0a  ion is provided.
12b0: 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c  ** for use in DL
12c0: 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65  Ls since DLL use
12d0: 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f  rs usually do no
12e0: 74 20 68 61 76 65 20 64 69 72 65 63 74 20 61 63  t have direct ac
12f0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a  cess to string.*
1300: 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68  * constants with
1310: 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a  in the DLL..**.*
1320: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1330: 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54 68 65  .** {H10021} The
1340: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
1350: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69  sion_number()] i
1360: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72  nterface shall r
1370: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
1380: 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75    an integer equ
1390: 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45  al to [SQLITE_VE
13a0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a  RSION_NUMBER]..*
13b0: 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20 54 68  *.** {H10022} Th
13c0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69  e [sqlite3_versi
13d0: 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  on] string const
13e0: 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69  ant shall contai
13f0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
1400: 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 5b 53  e text of the [S
1410: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73  QLITE_VERSION] s
1420: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
1430: 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  0023} The [sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d  e3_libversion()]
1450: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
1460: 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
1470: 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20     a pointer to 
1480: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72  the [sqlite3_ver
1490: 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e  sion] string con
14a0: 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  stant..*/.SQLITE
14b0: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
14c0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
14d0: 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72  on[];.const char
14e0: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
14f0: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  sion(void);.int 
1500: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1510: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
1520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1530: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1540: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1550: 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 30 31  Threadsafe {H101
1560: 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a  00} <S60100>.**.
1570: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1580: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1590: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
15a0: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
15b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
15c0: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
15d0: 6f 72 20 6d 61 63 72 6f 20 31 20 6f 72 20 32 2c  or macro 1 or 2,
15e0: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
15f0: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1600: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1610: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1620: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1630: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1640: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1650: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1660: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1670: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1680: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1690: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
16a0: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
16b0: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
16c0: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
16d0: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
16e0: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
16f0: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1700: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1710: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1720: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1730: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1740: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1750: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1760: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1770: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1780: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  ** The default b
1790: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
17a0: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
17b0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
17c0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
17d0: 65 20 75 73 65 64 20 62 79 20 61 20 70 72 6f 67  e used by a prog
17e0: 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ram to make sure
17f0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72   that the.** ver
1800: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74  sion of SQLite t
1810: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e  hat it is linkin
1820: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f  g against was co
1830: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
1840: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69  he desired setti
1850: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ng of the [SQLIT
1860: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1870: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cro..**.** This 
1880: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
1890: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f  eports on the co
18a0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78  mpile-time mutex
18b0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74   setting.** of t
18c0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
18d0: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66  DSAFE] flag.  If
18e0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
18f0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49  led with.** SQLI
1900: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20  TE_THREADSAFE=1 
1910: 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65  then mutexes are
1920: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
1930: 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62  ult but.** can b
1940: 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69  e fully or parti
1950: 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73  ally disabled us
1960: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
1970: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
1980: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72  .** with the ver
1990: 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  bs [SQLITE_CONFI
19a0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c  G_SINGLETHREAD],
19b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
19c0: 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a  MULTITHREAD],.**
19d0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
19e0: 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20  IG_MUTEX].  The 
19f0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
1a00: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
1a10: 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20  ows.** only the 
1a20: 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d  default compile-
1a30: 74 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f  time setting, no
1a40: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
1a50: 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61  hanges.** to tha
1a60: 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  t setting..**.**
1a70: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
1a80: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
1a90: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
1aa0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1ab0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  on..**.** INVARI
1ac0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ANTS:.**.** {H10
1ad0: 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  101} The [sqlite
1ae0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1af0: 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72  function shall r
1b00: 65 74 75 72 6e 20 7a 65 72 6f 20 69 66 0a 2a 2a  eturn zero if.**
1b10: 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6f 6e            and on
1b20: 6c 79 20 69 66 20 53 51 4c 69 74 65 20 77 61 73  ly if SQLite was
1b30: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1b40: 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69  utexing code omi
1b50: 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  tted..**.** {H10
1b60: 31 30 32 7d 20 54 68 65 20 76 61 6c 75 65 20 72  102} The value r
1b70: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 5b  eturned by the [
1b80: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1b90: 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  fe()] function.*
1ba0: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
1bb0: 20 72 65 6d 61 69 6e 20 74 68 65 20 73 61 6d 65   remain the same
1bc0: 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f   across calls to
1bd0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
1be0: 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1bf0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76  te3_threadsafe(v
1c00: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
1c10: 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
1c20: 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c  Connection Handl
1c30: 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30 32  e {H12000} <S402
1c40: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1c50: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
1c60: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
1c70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
1c80: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
1c90: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
1ca0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
1cb0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1cc0: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
1cd0: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
1ce0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
1cf0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
1d00: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
1d10: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
1d20: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
1d30: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
1d40: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1d50: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1d60: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
1d70: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
1d80: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
1d90: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
1da0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
1db0: 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 75  ** is its destru
1dc0: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65  ctor.  There are
1dd0: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65   many other inte
1de0: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
1df0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1e00: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
1e10: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1e20: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
1e30: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1e40: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
1e50: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
1e60: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
1e70: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
1e80: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
1e90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
1ea0: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
1eb0: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
1ec0: 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b 48  Integer Types {H
1ed0: 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a  10200} <S10110>.
1ee0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
1ef0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
1f00: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
1f10: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
1f20: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
1f30: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
1f40: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
1f50: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
1f60: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
1f70: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
1f80: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
1f90: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
1fa0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
1fb0: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
1fc0: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
1fd0: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69  ferred type defi
1fe0: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nitions..** The 
1ff0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64  sqlite_int64 and
2000: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
2010: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74  ypes are support
2020: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
2030: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
2040: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e  y only..**.** IN
2050: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2060: 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b 73 71  {H10201} The [sq
2070: 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20  lite_int64] and 
2080: 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20  [sqlite3_int64] 
2090: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
20a0: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
20b0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
20c0: 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nteger..**.** {H
20d0: 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  10202} The [sqli
20e0: 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b  te_uint64] and [
20f0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d 20  sqlite3_uint64] 
2100: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
2110: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
2120: 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
2130: 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66   integer..*/.#if
2140: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2150: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
2160: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2170: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
2180: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2190: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
21a0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
21b0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
21c0: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
21d0: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
21e0: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
21f0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2200: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2210: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2220: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2230: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2240: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2250: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2260: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
2270: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2280: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
2290: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
22a0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
22b0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
22c0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
22d0: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
22e0: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
22f0: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2300: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2310: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2320: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2330: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2340: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2350: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
2360: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
2370: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
2380: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
2390: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
23a0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
23b0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
23c0: 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c  ction {H12010} <
23d0: 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a  S30100><S40200>.
23e0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
23f0: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2400: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2410: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2420: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
2430: 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65  s should [sqlite
2440: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2450: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2460: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2470: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2480: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2490: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
24a0: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
24b0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
24c0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
24d0: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
24e0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
24f0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20   object..** The 
2500: 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2510: 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  mt()] interface 
2520: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
2530: 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72  ocate all.** [pr
2540: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2550: 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  s] associated wi
2560: 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
2570: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64 65  onnection] if de
2580: 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61  sired..** Typica
2590: 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f  l code might loo
25a0: 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  k like this:.**.
25b0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
25c0: 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  pre>.** sqlite3_
25d0: 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20  stmt *pStmt;.** 
25e0: 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d 20  while( (pStmt = 
25f0: 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2600: 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a  t(db, 0))!=0 ){.
2610: 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c 69  ** &nbsp;   sqli
2620: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74  te3_finalize(pSt
2630: 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70  mt);.** }.** </p
2640: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
2650: 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  .**.** If [sqlit
2660: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69  e3_close()] is i
2670: 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74  nvoked while a t
2680: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
2690: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
26a0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
26b0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
26c0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ack..**.** INVAR
26d0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
26e0: 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 73 66  2011} A successf
26f0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2700: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68  te3_close(C)] sh
2710: 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 65 0a  all destroy the.
2720: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
2730: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2740: 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a  ] object C..**.*
2750: 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73 75 63  * {H12012} A suc
2760: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2770: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2780: 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  )] shall return 
2790: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a  SQLITE_OK..**.**
27a0: 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75 63 63   {H12013} A succ
27b0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
27c0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
27d0: 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 65 20  ] shall release 
27e0: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
27f0: 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 74 65  memory and syste
2800: 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f  m resources asso
2810: 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 61 74  ciated with [dat
2820: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2830: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e  ].**          C.
2840: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 7d 20  .**.** {H12014} 
2850: 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
2860: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20  e3_close(C)] on 
2870: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
2880: 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a  ection] C that.*
2890: 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 20 6f  *          has o
28a0: 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20  ne or more open 
28b0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28c0: 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c  ents] shall fail
28d0: 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
28e0: 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53    an [SQLITE_BUS
28f0: 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a  Y] error code..*
2900: 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 41 20  *.** {H12015} A 
2910: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2920: 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72 65  _close(C)] where
2930: 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   C is a NULL poi
2940: 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  nter shall.**   
2950: 20 20 20 20 20 20 20 62 65 20 61 20 68 61 72 6d         be a harm
2960: 6c 65 73 73 20 6e 6f 2d 6f 70 20 72 65 74 75 72  less no-op retur
2970: 6e 69 6e 67 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  ning SQLITE_OK..
2980: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 39 7d 20 57  **.** {H12019} W
2990: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  hen [sqlite3_clo
29a0: 73 65 28 43 29 5d 20 69 73 20 69 6e 76 6f 6b 65  se(C)] is invoke
29b0: 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65  d on a [database
29c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 0a 2a   connection] C.*
29d0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
29e0: 68 61 73 20 61 20 70 65 6e 64 69 6e 67 20 74 72  has a pending tr
29f0: 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 20 74  ansaction, the t
2a00: 72 61 6e 73 61 63 74 69 6f 6e 20 73 68 61 6c 6c  ransaction shall
2a10: 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   be.**          
2a20: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
2a30: 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
2a40: 2a 2a 0a 2a 2a 20 7b 41 31 32 30 31 36 7d 20 54  **.** {A12016} T
2a50: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74  he C parameter t
2a60: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
2a70: 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74  (C)] must be eit
2a80: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20  her a NULL.**   
2a90: 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 6f         pointer o
2aa0: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2ab0: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2ac0: 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  tained.**       
2ad0: 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33     from [sqlite3
2ae0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2af0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
2b00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2b10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2b20: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
2b30: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a  usly closed..*/.
2b40: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2b50: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2b60: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2b70: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2b80: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2b90: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2ba0: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2bb0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2bc0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2bd0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2be0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2bf0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2c00: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2c10: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2c20: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2c30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2c40: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2c50: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2c60: 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30  e {H12100} <S100
2c70: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
2c90: 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76  erface is a conv
2ca0: 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75  enient way of ru
2cb0: 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72  nning one or mor
2cc0: 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
2cd0: 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69  nts without havi
2ce0: 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f  ng to write a lo
2cf0: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68  t of C code.  Th
2d00: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a  e UTF-8 encoded.
2d10: 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
2d20: 73 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20  s are passed in 
2d30: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
2d40: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2d50: 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68  e3_exec()..** Th
2d60: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  e statements are
2d70: 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62   evaluated one b
2d80: 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68  y one until eith
2d90: 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a  er an error or.*
2da0: 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69  * an interrupt i
2db0: 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f  s encountered, o
2dc0: 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65  r until they are
2dd0: 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20   all done.  The 
2de0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  3rd parameter.**
2df0: 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20   is an optional 
2e00: 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73  callback that is
2e10: 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
2e20: 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e  r each row of an
2e30: 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c  y query.** resul
2e40: 74 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74  ts produced by t
2e50: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2e60: 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61  s.  The 5th para
2e70: 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72  meter tells wher
2e80: 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e  e.** to write an
2e90: 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73  y error messages
2ea0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f  ..**.** The erro
2eb0: 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64  r message passed
2ec0: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
2ed0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
2ee0: 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65  is held.** in me
2ef0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2f00: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2f10: 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64  oc()].  To avoid
2f20: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a   a memory leak,.
2f30: 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61  ** the calling a
2f40: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
2f50: 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  d call [sqlite3_
2f60: 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65  free()] on any e
2f70: 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
2f80: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68  returned through
2f90: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
2fa0: 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  er when it has f
2fb0: 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a  inished using.**
2fc0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
2fd0: 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ge..**.** If the
2fe0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
2ff0: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  n the 2nd parame
3000: 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  ter is NULL or a
3010: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a  n empty string.*
3020: 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f  * or a string co
3030: 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68  ntaining only wh
3040: 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d  itespace and com
3050: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53  ments, then no S
3060: 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  QL.** statements
3070: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
3080: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  nd the database 
3090: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a  is not changed..
30a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
30b0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
30c0: 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
30d0: 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a  d in terms of.**
30e0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30f0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3100: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
3110: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3120: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ()]..** The sqli
3130: 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69  te3_exec() routi
3140: 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20  ne does nothing 
3150: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
3160: 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64  that cannot be d
3170: 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  one.** by [sqlit
3180: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
3190: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
31a0: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
31b0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
31c0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
31d0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 31 7d 20 41  **.** {H12101} A
31e0: 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
31f0: 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
3200: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
3210: 45 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E)].**          
3220: 73 68 61 6c 6c 20 73 65 71 75 65 6e 74 69 61 6c  shall sequential
3230: 6c 79 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20  ly evaluate all 
3240: 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  of the UTF-8 enc
3250: 6f 64 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  oded,.**        
3260: 20 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61    semicolon-sepa
3270: 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
3280: 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
3290: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
32a0: 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 53          string S
32b0: 20 77 69 74 68 69 6e 20 74 68 65 20 63 6f 6e 74   within the cont
32c0: 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ext of the [data
32d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32e0: 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30   D..**.** {H1210
32f0: 32 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  2} If the S para
3300: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3310: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3320: 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a  )] is NULL then.
3330: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
3340: 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 69  actions of the i
3350: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62  nterface shall b
3360: 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 69 66  e the same as if
3370: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
3380: 20 53 20 70 61 72 61 6d 65 74 65 72 20 77 65 72   S parameter wer
3390: 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  e an empty strin
33a0: 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 34  g..**.** {H12104
33b0: 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
33c0: 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  ue of [sqlite3_e
33d0: 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20  xec()] shall be 
33e0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61  [SQLITE_OK] if a
33f0: 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ll.**          S
3400: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75  QL statements ru
3410: 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61  n successfully a
3420: 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  nd to completion
3430: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 35 7d  ..**.** {H12105}
3440: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
3450: 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78  e of [sqlite3_ex
3460: 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 61  ec()] shall be a
3470: 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
3480: 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d 7a 65            non-ze
3490: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
34a0: 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61 74 65  if any SQL state
34b0: 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  ment fails..**.*
34c0: 2a 20 7b 48 31 32 31 30 37 7d 20 49 66 20 6f 6e  * {H12107} If on
34d0: 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
34e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
34f0: 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74  handed to [sqlit
3500: 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20  e3_exec()].**   
3510: 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 72 65         return re
3520: 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20 33 72  sults and the 3r
3530: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
3540: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a  ot NULL, then.**
3550: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61            the ca
3560: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3570: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
3580: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 73   3rd parameter s
3590: 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20  hall be.**      
35a0: 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65      invoked once
35b0: 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66   for each row of
35c0: 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b   result..**.** {
35d0: 48 31 32 31 31 30 7d 20 49 66 20 74 68 65 20 63  H12110} If the c
35e0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
35f0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65  a non-zero value
3600: 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65   then [sqlite3_e
3610: 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  xec()].**       
3620: 20 20 20 73 68 61 6c 6c 20 61 62 6f 72 74 20 74     shall abort t
3630: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3640: 20 69 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79   it is currently
3650: 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20   evaluating,.** 
3660: 20 20 20 20 20 20 20 20 20 73 6b 69 70 20 61 6c           skip al
3670: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  l subsequent SQL
3680: 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64   statements, and
3690: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
36a0: 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ABORT]..**.** {H
36b0: 31 32 31 31 33 7d 20 54 68 65 20 5b 73 71 6c 69  12113} The [sqli
36c0: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74  te3_exec()] rout
36d0: 69 6e 65 20 73 68 61 6c 6c 20 70 61 73 73 20 69  ine shall pass i
36e0: 74 73 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  ts 4th parameter
36f0: 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20 20 20   through.**     
3700: 20 20 20 20 20 61 73 20 74 68 65 20 31 73 74 20       as the 1st 
3710: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
3720: 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
3730: 20 7b 48 31 32 31 31 36 7d 20 54 68 65 20 5b 73   {H12116} The [s
3740: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
3750: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74  outine shall set
3760: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3770: 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20  er of its.**    
3780: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74        callback t
3790: 6f 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  o be the number 
37a0: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
37b0: 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
37c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
37d0: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ult..**.** {H121
37e0: 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
37f0: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65  _exec()] routine
3800: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 33   shall set the 3
3810: 72 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  rd parameter of 
3820: 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
3830: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61  callback to be a
3840: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3850: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68  ers to strings h
3860: 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  olding the.**   
3870: 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 66 6f         values fo
3880: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e  r each column in
3890: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73   the current res
38a0: 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73 0a 2a  ult set row as.*
38b0: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69  *          obtai
38c0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
38d0: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
38e0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 32 7d  ..**.** {H12122}
38f0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
3900: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  ec()] routine sh
3910: 61 6c 6c 20 73 65 74 20 74 68 65 20 34 74 68 20  all set the 4th 
3920: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73  parameter of its
3930: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
3940: 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61  lback to be an a
3950: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3960: 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64   to strings hold
3970: 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ing the.**      
3980: 20 20 20 20 6e 61 6d 65 73 20 6f 66 20 72 65 73      names of res
3990: 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f  ult columns as o
39a0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
39b0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
39c0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  e()]..**.** {H12
39d0: 31 32 35 7d 20 49 66 20 74 68 65 20 33 72 64 20  125} If the 3rd 
39e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
39f0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
3a00: 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20   NULL then.**   
3a10: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
3a20: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 69  exec()] shall si
3a30: 6c 65 6e 74 6c 79 20 64 69 73 63 61 72 64 20 71  lently discard q
3a40: 75 65 72 79 20 72 65 73 75 6c 74 73 2e 0a 2a 2a  uery results..**
3a50: 0a 2a 2a 20 7b 48 31 32 31 33 31 7d 20 49 66 20  .** {H12131} If 
3a60: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
3a70: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72  while parsing or
3a80: 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20   evaluating any 
3a90: 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20  of the SQL.**   
3aa0: 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
3ab0: 73 20 69 6e 20 74 68 65 20 53 20 70 61 72 61 6d  s in the S param
3ac0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
3ad0: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3ae0: 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20  ] and if.**     
3af0: 20 20 20 20 20 74 68 65 20 45 20 70 61 72 61 6d       the E param
3b00: 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  eter is not NULL
3b10: 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  , then [sqlite3_
3b20: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 74  exec()] shall st
3b30: 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
3b40: 69 6e 20 2a 45 20 61 6e 20 61 70 70 72 6f 70 72  in *E an appropr
3b50: 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
3b60: 67 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ge written into 
3b70: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a  memory obtained.
3b80: 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
3b90: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
3ba0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ()]..**.** {H121
3bb0: 33 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  34} The [sqlite3
3bc0: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3bd0: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
3be0: 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66  set the value of
3bf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 45 20  .**          *E 
3c00: 74 6f 20 4e 55 4c 4c 20 69 66 20 45 20 69 73 20  to NULL if E is 
3c10: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65  not NULL and the
3c20: 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73  re are no errors
3c30: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 37 7d  ..**.** {H12137}
3c40: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
3c50: 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66  ec(D,S,C,A,E)] f
3c60: 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65  unction shall se
3c70: 74 20 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64  t the [error cod
3c80: 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  e].**          a
3c90: 6e 64 20 6d 65 73 73 61 67 65 20 61 63 63 65 73  nd message acces
3ca0: 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74  sible via [sqlit
3cb0: 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 0a  e3_errcode()], .
3cc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3cd0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
3ce0: 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20  rcode()],.**    
3cf0: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
3d00: 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73  rrmsg()], and [s
3d10: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
3d20: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33  )]..**.** {H1213
3d30: 38 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  8} If the S para
3d40: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3d50: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3d60: 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  )] is NULL or an
3d70: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6d 70  .**          emp
3d80: 74 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e  ty string or con
3d90: 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74  tains nothing ot
3da0: 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70  her than whitesp
3db0: 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a  ace, comments,.*
3dc0: 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 2f 6f  *          and/o
3dd0: 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68  r semicolons, th
3de0: 65 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73  en results of [s
3df0: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
3e00: 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
3e10: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
3e20: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
3e30: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3e40: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
3e50: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3e60: 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
3e70: 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 74 6f    shall reset to
3e80: 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72 72   indicate no err
3e90: 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ors..**.** ASSUM
3ea0: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
3eb0: 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73 74  12141} The first
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
3ed0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6d  qlite3_exec()] m
3ee0: 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 20  ust be an valid 
3ef0: 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 20  and open.**     
3f00: 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
3f10: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
3f20: 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 20 64  * {A12142} The d
3f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3f40: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63  on must not be c
3f50: 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 20  losed while.**  
3f60: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
3f70: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
3f80: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31  ing..**.** {A121
3f90: 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  43} The calling 
3fa0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
3fb0: 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  use [sqlite3_fre
3fc0: 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20  e()] to free.** 
3fd0: 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d           the mem
3fe0: 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67  ory that *errmsg
3ff0: 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
4000: 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72  g at once the er
4010: 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ror.**          
4020: 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c 6f  message is no lo
4030: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a  nger needed..**.
4040: 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 65 20  ** {A12145} The 
4050: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
4060: 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61  xt in the 2nd pa
4070: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
4080: 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20  te3_exec()].**  
4090: 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 65 6d          must rem
40a0: 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77 68  ain unchanged wh
40b0: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ile [sqlite3_exe
40c0: 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  c()] is running.
40d0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
40e0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
40f0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4120: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4130: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4150: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4160: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4170: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4180: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4190: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
41a0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
41b0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
41c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
41f0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4200: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4210: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4230: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4240: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4250: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4260: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31  Result Codes {H1
4270: 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  0210} <S10700>.*
4280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4290: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
42a0: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
42b0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
42c0: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
42d0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
42e0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
42f0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
4300: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
4310: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
4320: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
4330: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4340: 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72  cates success or
4350: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
4360: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
4370: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
4380: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
4390: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
43a0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
43b0: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
43c0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
43d0: 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  codes].*/.#defin
43e0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
43f0: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4400: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4410: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4420: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4440: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4450: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
4460: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
4470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4480: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
4490: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
44a0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
44b0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
44c0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
44d0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
44e0: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
44f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4500: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4510: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4520: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4530: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4550: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4560: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4570: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
4580: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4590: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
45a0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
45b0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
45c0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
45d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
45e0: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
45f0: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4600: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4610: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4620: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4630: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4640: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4660: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4670: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
4680: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
4690: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
46a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46b0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
46c0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
46d0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
46e0: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
46f0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4700: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4710: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4720: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4730: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4740: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4750: 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53    12   /* NOT US
4760: 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63  ED. Table or rec
4770: 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f  ord not found */
4780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4790: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
47a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
47b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
47c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
47d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
47f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4800: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4810: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4820: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
4830: 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55     15   /* NOT U
4840: 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f  SED. Database lo
4850: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f  ck protocol erro
4860: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4870: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20  ITE_EMPTY       
4880: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  16   /* Database
4890: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65   is empty */.#de
48a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45  fine SQLITE_SCHE
48b0: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20  MA      17   /* 
48c0: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  The database sch
48d0: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23  ema changed */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f  define SQLITE_TO
48f0: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f  OBIG      18   /
4900: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  * String or BLOB
4910: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69   exceeds size li
4920: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mit */.#define S
4930: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
4940: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20    19   /* Abort 
4950: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e  due to constrain
4960: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23  t violation */.#
4970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4980: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f  SMATCH    20   /
4990: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d  * Data type mism
49a0: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20  atch */.#define 
49b0: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20  SQLITE_MISUSE   
49c0: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61     21   /* Libra
49d0: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63  ry used incorrec
49e0: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tly */.#define S
49f0: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20  QLITE_NOLFS     
4a00: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f    22   /* Uses O
4a10: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73  S features not s
4a20: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74  upported on host
4a30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a40: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32  TE_AUTH        2
4a50: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61  3   /* Authoriza
4a60: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  tion denied */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f  define SQLITE_FO
4a80: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f  RMAT      24   /
4a90: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61  * Auxiliary data
4aa0: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f  base format erro
4ab0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4ac0: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20  ITE_RANGE       
4ad0: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61  25   /* 2nd para
4ae0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4af0: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e  _bind out of ran
4b00: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge */.#define SQ
4b10: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20  LITE_NOTADB     
4b20: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70   26   /* File op
4b30: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74  ened that is not
4b40: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
4b50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b60: 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31  TE_ROW         1
4b70: 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  00  /* sqlite3_s
4b80: 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65  tep() has anothe
4b90: 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23  r row ready */.#
4ba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f  define SQLITE_DO
4bb0: 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f  NE        101  /
4bc0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
4bd0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
4be0: 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e  ecuting */./* en
4bf0: 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  d-of-error-codes
4c00: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
4c10: 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65  REF: Extended Re
4c20: 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30 32  sult Codes {H102
4c30: 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20  20} <S10700>.** 
4c40: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c50: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4c60: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4c70: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4c80: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c90: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4ca0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4cb0: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4cc0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4cd0: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4ce0: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4cf0: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4d00: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4d10: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4d20: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4d30: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4d40: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4d50: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4d60: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4d70: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4d80: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d90: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4da0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4db0: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4dc0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4dd0: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4de0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4df0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4e00: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4e10: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4e20: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4e30: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4e40: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4e50: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4e60: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4e70: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4e80: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e90: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4ea0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4eb0: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4ec0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4ed0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4ee0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4ef0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4f00: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4f10: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4f20: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4f30: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4f40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f50: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4f60: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4f70: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4f80: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f90: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4fa0: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4fb0: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4fc0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4fd0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4fe0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4ff0: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
5000: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
5010: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
5020: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
5030: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
5040: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
5050: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
5060: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
5070: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a  exactly zero..**
5080: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
5090: 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d 20 54  **.** {H10223} T
50a0: 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
50b0: 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64   for an extended
50c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68 61   result code sha
50d0: 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  ll contains.**  
50e0: 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74 65          a relate
50f0: 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74  d primary result
5100: 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 69   code as a prefi
5110: 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 34  x..**.** {H10224
5120: 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74  } Primary result
5130: 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c   code names shal
5140: 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67  l contain a sing
5150: 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72  le "_" character
5160: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 35 7d  ..**.** {H10225}
5170: 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   Extended result
5180: 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c   code names shal
5190: 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72  l contain two or
51a0: 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63   more "_" charac
51b0: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ters..**.** {H10
51c0: 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 63  226} The numeric
51d0: 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 74   value of an ext
51e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
51f0: 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20  e shall contain 
5200: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
5210: 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66  numeric value of
5220: 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64 69   its correspondi
5230: 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c  ng primary resul
5240: 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20 20  t code in.**    
5250: 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74 20        its least 
5260: 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62 69  significant 8 bi
5270: 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ts..*/.#define S
5280: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
5290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
52a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
52b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
52d0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
52e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
52f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5300: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
5310: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5320: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
5330: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5340: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
5350: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5360: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
5390: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
53b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53c0: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
53d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
53e0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
53f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5400: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
5410: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5420: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
5430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5440: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5450: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5460: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5480: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5490: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54a0: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
54b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54c0: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
54d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
54e0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
54f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5500: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
5510: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5520: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5540: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5560: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5580: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5590: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55a0: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
55b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55c0: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
55d0: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
55e0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
55f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5600: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
5610: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5620: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
5630: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5640: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5650: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5660: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5670: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5680: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5690: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
56a0: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 0a 2f  RR | (17<<8))../
56b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
56c0: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
56d0: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48  en Operations {H
56e0: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20  10230} <H11120> 
56f0: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12700>.**.** T
5700: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
5710: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
5720: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
5730: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
5740: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
5750: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
5760: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
5770: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
5780: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
5790: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
57a0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
57b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
57c0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
57d0: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
57e0: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
57f0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
5800: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
5810: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5820: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
5830: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5840: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
5850: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
5860: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
5870: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
5880: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
5890: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
58a0: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
58b0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
58c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
58d0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
58e0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
58f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5900: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
5910: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
5920: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
5930: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
5940: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
5950: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5960: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
5970: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
5980: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5990: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
59a0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
59b0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
59c0: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  2000.#define SQL
59d0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
59e0: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
59f0: 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  4000.#define SQL
5a00: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
5a10: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a20: 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  8000.#define SQL
5a30: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
5a40: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
5a50: 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0000../*.** CAPI
5a60: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5a70: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
5a80: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
5a90: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5aa0: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
5ab0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
5ac0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
5ad0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
5ae0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
5af0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5b00: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5b10: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5b20: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5b30: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5b40: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5b50: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5b60: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5b70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5b80: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5b90: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
5ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5bb0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
5bc0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
5bd0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
5be0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
5bf0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5c00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5c10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5c20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5c30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5c40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5c50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5c60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5c70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5c80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5c90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
5ca0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5cb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
5cc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
5cd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
5ce0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
5cf0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5d00: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5d10: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5d20: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5d30: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5d40: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5d50: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5d60: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5d70: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5d80: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5d90: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
5da0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
5db0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
5dc0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
5dd0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
5de0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5df0: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
5e00: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5e10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e20: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
5e30: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
5e40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e50: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
5e60: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
5e70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e80: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
5e90: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
5ea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5eb0: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
5ec0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5ed0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ee0: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
5ef0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
5f00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f10: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
5f20: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
5f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f40: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
5f50: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
5f60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f70: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
5f80: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
5f90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5fa0: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
5fb0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
5fc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
5fd0: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
5fe0: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
5ff0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6000: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
6010: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
6020: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
6030: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
6040: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6050: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6060: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
6070: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
6080: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
6090: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
60a0: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
60b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
60c0: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
60d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
60e0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
60f0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
6100: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
6110: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
6120: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6130: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
6140: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
6150: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
6160: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6170: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
6180: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
6190: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
61a0: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
61b0: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
61c0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
61d0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
61e0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
61f0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6200: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6210: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
6220: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
6230: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6240: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6250: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
6260: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
6270: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6280: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
6290: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
62a0: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
62b0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
62c0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
62d0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
62e0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
62f0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
6300: 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54  ushed. The SQLIT
6310: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c  E_SYNC_NORMAL fl
6320: 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  ag means.** to u
6330: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
6340: 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65  ) semantics. The
6350: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6360: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20  L flag means.** 
6370: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
6380: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
6390: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
63a0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
63b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
63c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
63d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
63e0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
63f0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
6400: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6410: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
6420: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
6430: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
6440: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
6450: 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30  le {H11110} <S20
6460: 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  110>.**.** An [s
6470: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6480: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
6490: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
64a0: 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61  he OS.** interfa
64b0: 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76  ce layer.  Indiv
64c0: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
64d0: 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ce implementatio
64e0: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
64f0: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
6500: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
6510: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
6520: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
6530: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
6540: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
6550: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
6560: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6570: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6580: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
6590: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
65a0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
65b0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
65c0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
65d0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
65e0: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
65f0: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
6600: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
6610: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
6620: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
6630: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
6640: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
6650: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
6660: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6670: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
6680: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
6690: 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30 7d   Object {H11120}
66a0: 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S20110>.**.** 
66b0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
66c0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
66d0: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74  3_vfs] xOpen met
66e0: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
66f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
6700: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
6710: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
6720: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
6730: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
6740: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
6750: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
6760: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
6770: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
6780: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
6790: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
67a0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
67b0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
67c0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
67d0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
67e0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
67f0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
6800: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
6810: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
6820: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
6830: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
6840: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
6850: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
6860: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
6870: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
6880: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
6890: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
68a0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
68b0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
68c0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
68d0: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
68e0: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
68f0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
6900: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
6910: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
6920: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
6930: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
6940: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
6950: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
6960: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6970: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
6980: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6990: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
69a0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
69b0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
69c0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
69d0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
69e0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
69f0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
6a00: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
6a10: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6a20: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
6a30: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
6a40: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
6a50: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
6a60: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
6a70: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
6a80: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
6a90: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
6aa0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
6ab0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
6ac0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
6ad0: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
6ae0: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
6af0: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
6b00: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
6b10: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
6b20: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
6b30: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
6b40: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
6b50: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
6b60: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
6b70: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
6b80: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
6b90: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
6ba0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
6bb0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
6bc0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
6bd0: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
6be0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
6bf0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
6c00: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
6c10: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
6c20: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
6c30: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
6c40: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
6c50: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
6c60: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
6c70: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
6c80: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
6c90: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
6ca0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
6cb0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
6cc0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
6cd0: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
6ce0: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
6cf0: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
6d00: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
6d10: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
6d20: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
6d30: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
6d40: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
6d50: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
6d60: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
6d70: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
6d80: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
6d90: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
6da0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
6db0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
6dc0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
6dd0: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
6de0: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
6df0: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
6e00: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
6e10: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
6e20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
6e30: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
6e40: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
6e50: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
6e60: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
6e70: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
6e80: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
6e90: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
6ea0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
6eb0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
6ec0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
6ed0: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nflicts..**.** T
6ee0: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
6ef0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6f00: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
6f10: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
6f20: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
6f30: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
6f40: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
6f50: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
6f60: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
6f70: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
6f80: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
6f90: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
6fa0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
6fb0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6fc0: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
6fd0: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
6fe0: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
6ff0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
7000: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
7010: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
7020: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7030: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
7040: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7050: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
7060: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7070: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
7080: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7090: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
70a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
70c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
70e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
7100: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7110: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
7120: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7130: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
7140: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7150: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
7160: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
7170: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
7180: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
7190: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
71a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
71b0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
71c0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
71d0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
71e0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
71f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7200: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
7210: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
7220: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
7230: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
7240: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
7250: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
7260: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
7270: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
7280: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
7290: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
72a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
72b0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
72c0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
72d0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
72e0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
72f0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
7300: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
7310: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
7320: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
7330: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
7340: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
7350: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
7360: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
7370: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
7380: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
7390: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
73a0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
73b0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
73c0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
73d0: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
73e0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
73f0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
7400: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
7410: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
7420: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
7430: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
7440: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
7450: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
7460: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
7470: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
7480: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
7490: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
74a0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
74b0: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
74c0: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
74d0: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
74e0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
74f0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7500: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
7510: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
7520: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
7530: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
7540: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
7550: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
7560: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7570: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
7580: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
7590: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
75a0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
75b0: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
75c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
75d0: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
75e0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
75f0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
7600: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
7610: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
7620: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
7630: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
7640: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7650: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
7660: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
7670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
7680: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
7690: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
76a0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
76b0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
76c0: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
76d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
76e0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
76f0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
7700: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
7710: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
7720: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
7730: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7740: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
7750: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
7760: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
7770: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
7780: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
7790: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
77a0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64  _file*);.  /* Ad
77b0: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
77c0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
77d0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
77e0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
77f0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
7800: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
7810: 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d 20 3c  codes {H11310} <
7820: 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30800>.**.** Th
7830: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
7840: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
7850: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
7860: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
7870: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
7880: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7890: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
78a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
78b0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
78c0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
78d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
78e0: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
78f0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
7900: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
7910: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
7920: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
7930: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
7940: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
7950: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
7960: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
7970: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
7980: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7990: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
79a0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
79b0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
79c0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
79d0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
79e0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
79f0: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
7a00: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
7a10: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
7a20: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
7a30: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
7a40: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
7a50: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
7a60: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
7a70: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
7a80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7a90: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
7aa0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
7ab0: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
7ac0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
7ad0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7ae0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
7af0: 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  LE      3.#defin
7b00: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
7b10: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
7b20: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
7b30: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20  F: Mutex Handle 
7b40: 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31 33 30  {H17110} <S20130
7b50: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  >.**.** The mute
7b60: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
7b70: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
7b80: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
7b90: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
7ba0: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
7bb0: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
7bc0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
7bd0: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
7be0: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
7bf0: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
7c00: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
7c10: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
7c20: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
7c30: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
7c40: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
7c50: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
7c60: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
7c70: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
7c80: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
7c90: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7ca0: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
7cb0: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
7cc0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7cd0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b  terface Object {
7ce0: 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30 30 3e  H11140} <S20100>
7cf0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
7d00: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
7d10: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
7d20: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
7d30: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
7d40: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
7d50: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
7d60: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7d70: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
7d80: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
7d90: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
7da0: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
7db0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a  ile system"..**.
7dc0: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
7dd0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
7de0: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
7df0: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
7e00: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
7e10: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
7e20: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
7e30: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
7e40: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
7e50: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
7e60: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
7e70: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
7e80: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
7e90: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
7ea0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
7eb0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
7ec0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
7ed0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
7ee0: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
7ef0: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
7f00: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
7f10: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
7f20: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
7f30: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
7f40: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
7f50: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
7f60: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
7f70: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
7f80: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
7f90: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
7fa0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
7fb0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
7fc0: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
7fd0: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
7fe0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
7ff0: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
8000: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
8010: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
8020: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
8030: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
8040: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
8050: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
8060: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
8070: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
8080: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
8090: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
80a0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
80b0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
80c0: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
80d0: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
80e0: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
80f0: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
8100: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
8110: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
8120: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
8130: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
8140: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
8150: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
8160: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
8170: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
8180: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
8190: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
81a0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
81b0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
81c0: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
81d0: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
81e0: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
81f0: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
8200: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
8210: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
8220: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
8230: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
8240: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
8250: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
8260: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
8270: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
8280: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
8290: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
82a0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
82b0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
82c0: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
82d0: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
82e0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72  SQLite will guar
82f0: 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 7a  antee that the z
8300: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
8310: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
8320: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
8330: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
8340: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
8350: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
8360: 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72 74  ().  SQLite furt
8370: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
8380: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
8390: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
83a0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
83b0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
83c0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
83d0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
83e0: 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a 2a 20  us sentense,.** 
83f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8400: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
8410: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
8420: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
8430: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
8440: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
8450: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
8460: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
8470: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
8480: 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 69 73  eter is xOpen is
8490: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
84a0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
84b0: 73 74 20 69 6e 76 69 74 65 20 69 74 73 20 6f 77  st invite its ow
84c0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
84d0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
84e0: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
84f0: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
8500: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
8510: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
8520: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
8530: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
8540: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
8550: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8560: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
8570: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
8580: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
8590: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
85a0: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
85b0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
85c0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
85d0: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
85e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
85f0: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
8600: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
8610: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
8620: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
8630: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
8640: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
8650: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
8660: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
8670: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
8680: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
8690: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
86a0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
86b0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
86c0: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
86d0: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
86e0: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
86f0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73   SQLite will als
8700: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
8710: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
8720: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
8730: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
8740: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
8750: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
8760: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8770: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8780: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
8790: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
87a0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
87b0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
87c0: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
87d0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
87e0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
87f0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8800: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
8810: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
8820: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
8830: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
8840: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
8850: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
8860: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  /ul>.**.** The f
8870: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
8880: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
8890: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
88a0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
88b0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
88c0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
88d0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
88e0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
88f0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
8900: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
8910: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
8920: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
8930: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
8940: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
8950: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
8960: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
8970: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
8980: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
8990: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
89a0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
89b0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
89c0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
89d0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
89e0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
89f0: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
8a00: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
8a10: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
8a20: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
8a30: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
8a40: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
8a50: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
8a60: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
8a70: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
8a80: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
8a90: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
8aa0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
8ab0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
8ac0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
8ad0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8ae0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8af0: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
8b00: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8b10: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
8b20: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
8b30: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8b40: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
8b50: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8b60: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
8b70: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
8b80: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8b90: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
8ba0: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
8bb0: 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73  or TEMP  databas
8bc0: 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64  es, journals and
8bd0: 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73   for subjournals
8be0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
8bf0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8c00: 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  VE] flag means t
8c10: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
8c20: 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20  e opened.** for 
8c30: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8c40: 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 73 20  .  This flag is 
8c50: 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65  set for all file
8c60: 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20  s except.** for 
8c70: 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
8c80: 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 74  e file..**.** At
8c90: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
8ca0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
8cb0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
8cc0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
8cd0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
8ce0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
8cf0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
8d00: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
8d10: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
8d20: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
8d30: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
8d40: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
8d50: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
8d60: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
8d70: 69 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  in..**.** The fl
8d80: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
8d90: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
8da0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
8db0: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
8dc0: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
8dd0: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
8de0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8df0: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
8e00: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
8e10: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
8e20: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
8e30: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
8e40: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
8e50: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
8e60: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
8e70: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
8e80: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
8e90: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
8ea0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
8eb0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
8ec0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
8ed0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
8ee0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
8ef0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
8f00: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
8f10: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
8f20: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
8f30: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
8f40: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
8f50: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
8f60: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
8f70: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
8f80: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
8f90: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
8fa0: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
8fb0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
8fc0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
8fd0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
8fe0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
8ff0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
9000: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
9010: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
9020: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
9030: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
9040: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
9050: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
9060: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
9070: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
9080: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
9090: 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c   are not strictl
90a0: 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20  y a part of the 
90b0: 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20  filesystem, but 
90c0: 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c  they are.** incl
90d0: 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20  uded in the VFS 
90e0: 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f  structure for co
90f0: 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54  mpleteness..** T
9100: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
9110: 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70   function attemp
9120: 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79  ts to return nBy
9130: 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  tes bytes.** of 
9140: 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e  good-quality ran
9150: 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75  domness into zOu
9160: 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  t.  The return v
9170: 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61  alue is.** the a
9180: 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  ctual number of 
9190: 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
91a0: 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a  ess obtained..**
91b0: 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   The xSleep() me
91c0: 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20  thod causes the 
91d0: 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74  calling thread t
91e0: 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a  o sleep for at.*
91f0: 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  * least the numb
9200: 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e  er of microsecon
9210: 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78  ds given.  The x
9220: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
9230: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
9240: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
9250: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
9260: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
9270: 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66  e..**.*/.typedef
9280: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
9290: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
92a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
92b0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
92c0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
92d0: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
92e0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  rsion number */.
92f0: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
9300: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
9310: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
9320: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
9330: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
9340: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
9350: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
9360: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
9370: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
9380: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
9390: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
93a0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
93b0: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
93c0: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
93d0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
93e0: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
93f0: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
9400: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
9410: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
9420: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
9430: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
9440: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
9450: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
9460: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
9470: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
9480: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
9490: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
94a0: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
94b0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
94c0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
94d0: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
94e0: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
94f0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
9500: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
9510: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
9520: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
9530: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
9540: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
9550: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
9560: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
9570: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
9580: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
9590: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
95a0: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
95b0: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
95c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
95d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
95e0: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28  Msg);.  void (*(
95f0: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
9600: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
9610: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
9620: 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64  ))(void);.  void
9630: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
9640: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
9650: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
9660: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
9670: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
9680: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
9690: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
96a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
96b0: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
96c0: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
96d0: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
96e0: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69  *, double*);.  i
96f0: 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72  nt (*xGetLastErr
9700: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
9710: 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a  , int, char *);.
9720: 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    /* New fields 
9730: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
9740: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
9750: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
9760: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
9770: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
9780: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
9790: 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  s. */.};../*.** 
97a0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
97b0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
97c0: 56 46 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 31  VFS method {H111
97d0: 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a  90} <H11140>.**.
97e0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
97f0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
9800: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
9810: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
9820: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
9830: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
9840: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
9850: 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64  t. {END}  They d
9860: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
9870: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
9880: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
9890: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
98a0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
98b0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
98c0: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
98d0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
98e0: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
98f0: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
9900: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
9910: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
9920: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
9930: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
9940: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
9950: 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  e is both readab
9960: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e  le and writable.
9970: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
9980: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
9990: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
99a0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
99b0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
99c0: 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69  adable..*/.#defi
99d0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
99e0: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
99f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
9a00: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23  SS_READWRITE 1.#
9a10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
9a20: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
9a30: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9a40: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
9a50: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20   SQLite Library 
9a60: 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30  {H10130} <S20000
9a70: 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S30100>.**.** 
9a80: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9a90: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9aa0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
9ab0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
9ac0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
9ad0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
9ae0: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
9af0: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
9b00: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
9b10: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
9b20: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
9b30: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
9b40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9b50: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
9b60: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
9b70: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
9b80: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
9b90: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
9ba0: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
9bb0: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
9bc0: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
9bd0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
9be0: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
9bf0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
9c00: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
9c10: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
9c20: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9c30: 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63  .  Only an effec
9c40: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
9c50: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9c60: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
9c70: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
9c80: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
9c90: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
9ca0: 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  o-ops..**.** Amo
9cb0: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
9cc0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9cd0: 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f  ize() shall invo
9ce0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
9cf0: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
9d00: 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75  rly, sqlite3_shu
9d10: 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c  tdown().** shall
9d20: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
9d30: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
9d40: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
9d50: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
9d60: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
9d70: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
9d80: 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20  .** If for some 
9d90: 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  reason, sqlite3_
9da0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
9db0: 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61  unable to initia
9dc0: 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72  lize.** the libr
9dd0: 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20  ary (perhaps it 
9de0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
9df0: 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72  ocate a needed r
9e00: 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20  esource such.** 
9e10: 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72  as a mutex) it r
9e20: 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72  eturns an [error
9e30: 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61   code] other tha
9e40: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  n [SQLITE_OK]..*
9e50: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
9e60: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
9e70: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
9e80: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
9e90: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
9ea0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
9eb0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
9ec0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
9ed0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
9ee0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
9ef0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
9f00: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
9f10: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
9f20: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
9f30: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9f40: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
9f50: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
9f60: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
9f70: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
9f80: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
9f90: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
9fa0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
9fb0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
9fc0: 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76 65 72  lready.  However
9fd0: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
9fe0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
9ff0: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
a000: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
a010: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
a020: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
a030: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
a040: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a050: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
a060: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
a070: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
a080: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a090: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
a0a0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
a0b0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
a0c0: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
a0d0: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
a0e0: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
a0f0: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
a100: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
a110: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
a120: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
a130: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
a140: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
a150: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a160: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
a170: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
a180: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
a190: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
a1a0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
a1b0: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
a1c0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
a1d0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
a1e0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
a1f0: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
a200: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
a210: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
a220: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
a230: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
a240: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
a250: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
a260: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
a270: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
a280: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
a290: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
a2a0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
a2b0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
a2c0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
a2d0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
a2e0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
a2f0: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
a300: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
a310: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
a320: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
a330: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
a340: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
a350: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
a360: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
a370: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
a380: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
a390: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
a3a0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
a3b0: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
a3c0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
a3d0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
a3e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
a3f0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
a400: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
a410: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
a420: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a430: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
a440: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
a450: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
a460: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
a470: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
a480: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
a490: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
a4a0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
a4b0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
a4c0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
a4d0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
a4e0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
a4f0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
a500: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a510: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
a520: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a530: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
a540: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a550: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
a560: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
a570: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
a580: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
a590: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
a5a0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75  s compiled for u
a5b0: 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72  nix, windows, or
a5c0: 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62   os/2..** When b
a5d0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
a5e0: 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20  latforms (using 
a5f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
a600: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
a610: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
a620: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
a630: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
a640: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
a650: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
a660: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
a670: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
a680: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
a690: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
a6a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a6b0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
a6c0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
a6d0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
a6e0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
a6f0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
a700: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
a710: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
a720: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
a730: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
a740: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
a750: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
a760: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
a770: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
a780: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
a790: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
a7a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
a7b0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
a7c0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48  QLite Library {H
a7d0: 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c  14100} <S20000><
a7e0: 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S30200>.** EXPER
a7f0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
a800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
a810: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
a820: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
a830: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
a840: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
a850: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
a860: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
a870: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
a880: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
a890: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
a8a0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
a8b0: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
a8c0: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
a8d0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
a8e0: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
a8f0: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
a900: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
a910: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
a920: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
a930: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
a940: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
a950: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
a960: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
a970: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
a980: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
a990: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
a9a0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
a9b0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
a9c0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
a9d0: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
a9e0: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
a9f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
aa00: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
aa10: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
aa20: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
aa30: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
aa40: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
aa50: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
aa60: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
aa70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
aa80: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
aa90: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
aaa0: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
aab0: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
aac0: 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  hat sqlite3_conf
aad0: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
aae0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
aaf0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
ab00: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
ab10: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
ab20: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ab30: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
ab40: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
ab50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ab60: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
ab70: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
ab80: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
ab90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
aba0: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
abb0: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
abc0: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
abd0: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
abe0: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
abf0: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
ac00: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
ac10: 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
ac20: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
ac30: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
ac40: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
ac50: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ac60: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63  ..**.** When a c
ac70: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ac80: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
ac90: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
aca0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
acb0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69  ..** If the opti
acc0: 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
acd0: 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
ace0: 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
acf0: 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
ad00: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
ad10: 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
ad20: 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
ad30: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
ad40: 2a 20 7b 48 31 34 31 30 33 7d 20 41 20 73 75 63  * {H14103} A suc
ad50: 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
ad60: 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63  on of [sqlite3_c
ad70: 6f 6e 66 69 67 28 29 5d 20 73 68 61 6c 6c 20 72  onfig()] shall r
ad80: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
ad90: 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a    [SQLITE_OK]..*
ada0: 2a 0a 2a 2a 20 7b 48 31 34 31 30 36 7d 20 54 68  *.** {H14106} Th
adb0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
adc0: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  g()] interface s
add0: 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  hall return [SQL
ade0: 49 54 45 5f 4d 49 53 55 53 45 5d 0a 2a 2a 20 20  ITE_MISUSE].**  
adf0: 20 20 20 20 20 20 20 20 69 66 20 69 74 20 69 73          if it is
ae00: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 62 65 74 77   invoked in betw
ae10: 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  een calls to [sq
ae20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ae30: 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ()] and.**      
ae40: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 68 75      [sqlite3_shu
ae50: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  tdown()]..**.** 
ae60: 7b 48 31 34 31 32 30 7d 20 41 20 73 75 63 63 65  {H14120} A succe
ae70: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
ae80: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
ae90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
aea0: 4e 47 4c 45 54 48 52 45 41 44 5d 29 0a 2a 2a 20  NGLETHREAD]).** 
aeb0: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73           shall s
aec0: 65 74 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  et the default [
aed0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
aee0: 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
aef0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 33 7d  ..**.** {H14123}
af00: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
af10: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
af20: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
af30: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
af40: 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D]).**          
af50: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 64 65  shall set the de
af60: 66 61 75 6c 74 20 5b 74 68 72 65 61 64 69 6e 67  fault [threading
af70: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
af80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  thread..**.** {H
af90: 31 34 31 32 36 7d 20 41 20 73 75 63 63 65 73 73  14126} A success
afa0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
afb0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
afc0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
afd0: 41 4c 49 5a 45 44 5d 29 0a 2a 2a 20 20 20 20 20  ALIZED]).**     
afe0: 20 20 20 20 20 73 68 61 6c 6c 20 73 65 74 20 74       shall set t
aff0: 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68 72 65  he default [thre
b000: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
b010: 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  erialized..**.**
b020: 20 7b 48 31 34 31 32 39 7d 20 41 20 73 75 63 63   {H14129} A succ
b030: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
b040: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
b050: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
b060: 55 54 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20  UTEX],X).**     
b070: 20 20 20 20 20 77 68 65 72 65 20 58 20 69 73 20       where X is 
b080: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
b090: 69 6e 69 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c  initialized [sql
b0a0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
b0b0: 64 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ds].**          
b0c0: 6f 62 6a 65 63 74 20 73 68 61 6c 6c 20 63 61 75  object shall cau
b0d0: 73 65 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  se all subsequen
b0e0: 74 20 6d 75 74 65 78 20 6f 70 65 72 61 74 69 6f  t mutex operatio
b0f0: 6e 73 20 70 65 72 66 6f 72 6d 65 64 0a 2a 2a 20  ns performed.** 
b100: 20 20 20 20 20 20 20 20 20 62 79 20 53 51 4c 69           by SQLi
b110: 74 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 75  te to use the mu
b120: 74 65 78 20 6d 65 74 68 6f 64 73 20 74 68 61 74  tex methods that
b130: 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 69 6e   were present in
b140: 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64   X.**          d
b150: 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 74  uring the call t
b160: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b170: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  g()]..**.** {H14
b180: 31 33 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  132} A successfu
b190: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
b1a0: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b1b0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
b1c0: 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 20 20  EX],X).**       
b1d0: 20 20 20 77 68 65 72 65 20 58 20 69 73 20 61 20     where X is a 
b1e0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73  pointer to an [s
b1f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
b200: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 0a 2a 2a  hods] object .**
b210: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
b220: 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 63 6f  overwrite the co
b230: 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65  ntent of [sqlite
b240: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
b250: 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20   object.**      
b260: 20 20 20 20 77 69 74 68 20 74 68 65 20 6d 75 74      with the mut
b270: 65 78 20 6d 65 74 68 6f 64 73 20 63 75 72 72 65  ex methods curre
b280: 6e 74 6c 79 20 69 6e 20 75 73 65 20 62 79 20 53  ntly in use by S
b290: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  QLite..**.** {H1
b2a0: 34 31 33 35 7d 20 41 20 73 75 63 63 65 73 73 66  4135} A successf
b2b0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
b2c0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
b2d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
b2e0: 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20 20 20 20 20  C],M).**        
b2f0: 20 20 77 68 65 72 65 20 4d 20 69 73 20 61 20 70    where M is a p
b300: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 69  ointer to an ini
b310: 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c 69 74 65  tialized [sqlite
b320: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
b330: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63  *          objec
b340: 74 20 73 68 61 6c 6c 20 63 61 75 73 65 20 61 6c  t shall cause al
b350: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6d 65 6d  l subsequent mem
b360: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ory allocation o
b370: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 20 20 20  perations.**    
b380: 20 20 20 20 20 20 70 65 72 66 6f 72 6d 65 64 20        performed 
b390: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  by SQLite to use
b3a0: 20 74 68 65 20 6d 65 74 68 6f 64 73 20 74 68 61   the methods tha
b3b0: 74 20 77 65 72 65 20 70 72 65 73 65 6e 74 20 69  t were present i
b3c0: 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d  n .**          M
b3d0: 20 64 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c   during the call
b3e0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
b3f0: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  fig()]..**.** {H
b400: 31 34 31 33 38 7d 20 41 20 73 75 63 63 65 73 73  14138} A success
b410: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
b420: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
b430: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
b440: 41 4c 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20  ALLOC],M).**    
b450: 20 20 20 20 20 20 77 68 65 72 65 20 4d 20 69 73        where M is
b460: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
b470: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
b480: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 73 68  thods] object sh
b490: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
b4a0: 6f 76 65 72 77 72 69 74 65 20 74 68 65 20 63 6f  overwrite the co
b4b0: 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65  ntent of [sqlite
b4c0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 6f  3_mem_methods] o
b4d0: 62 6a 65 63 74 20 77 69 74 68 20 0a 2a 2a 20 20  bject with .**  
b4e0: 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d 6f          the memo
b4f0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6d 65  ry allocation me
b500: 74 68 6f 64 73 20 63 75 72 72 65 6e 74 6c 79 20  thods currently 
b510: 69 6e 20 75 73 65 20 62 79 0a 2a 2a 20 20 20 20  in use by.**    
b520: 20 20 20 20 20 20 53 51 4c 69 74 65 2e 0a 2a 2a        SQLite..**
b530: 0a 2a 2a 20 7b 48 31 34 31 34 31 7d 20 41 20 73  .** {H14141} A s
b540: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
b550: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b560: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
b570: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 31 29 0a  G_MEMSTATUS],1).
b580: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
b590: 6c 20 65 6e 61 62 6c 65 20 74 68 65 20 6d 65 6d  l enable the mem
b5a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
b5b0: 74 61 74 75 73 20 63 6f 6c 6c 65 63 74 69 6f 6e  tatus collection
b5c0: 20 6c 6f 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48   logic..**.** {H
b5d0: 31 34 31 34 34 7d 20 41 20 73 75 63 63 65 73 73  14144} A success
b5e0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
b5f0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
b600: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
b610: 54 41 54 55 53 5d 2c 30 29 0a 2a 2a 20 20 20 20  TATUS],0).**    
b620: 20 20 20 20 20 20 73 68 61 6c 6c 20 64 69 73 61        shall disa
b630: 62 6c 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ble the memory a
b640: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73  llocation status
b650: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69   collection logi
b660: 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 37  c..**.** {H14147
b670: 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  } The memory all
b680: 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63  ocation status c
b690: 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 20  ollection logic 
b6a0: 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20  shall be.**     
b6b0: 20 20 20 20 20 65 6e 61 62 6c 65 64 20 62 79 20       enabled by 
b6c0: 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b  default..**.** {
b6d0: 48 31 34 31 35 30 7d 20 41 20 73 75 63 63 65 73  H14150} A succes
b6e0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
b6f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
b700: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
b710: 41 54 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20  ATCH],S,Z,N).** 
b720: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a           where Z
b730: 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e   and N are non-n
b740: 65 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73  egative integers
b750: 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20   and .**        
b760: 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72    S is a pointer
b770: 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d   to an aligned m
b780: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74  emory buffer not
b790: 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20   less than.**   
b7a0: 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73         Z*N bytes
b7b0: 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63   in size shall c
b7c0: 61 75 73 65 20 53 20 74 6f 20 62 65 20 75 73 65  ause S to be use
b7d0: 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
b7e0: 20 20 20 20 20 5b 73 63 72 61 74 63 68 20 6d 65       [scratch me
b7f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
b800: 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73 20 4e  for as many as N
b810: 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73 0a 2a   simulataneous.*
b820: 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63  *          alloc
b830: 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66 20 73  ations each of s
b840: 69 7a 65 20 28 5a 20 26 20 7e 37 29 2e 0a 2a 2a  ize (Z & ~7)..**
b850: 0a 2a 2a 20 7b 48 31 34 31 35 33 7d 20 41 20 73  .** {H14153} A s
b860: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
b870: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b880: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
b890: 47 5f 53 43 52 41 54 43 48 5d 2c 53 2c 5a 2c 4e  G_SCRATCH],S,Z,N
b8a0: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  ).**          wh
b8b0: 65 72 65 20 53 20 69 73 20 61 20 4e 55 4c 4c 20  ere S is a NULL 
b8c0: 70 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 64 69  pointer shall di
b8d0: 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20 20 20  sable the.**    
b8e0: 20 20 20 20 20 20 5b 73 63 72 61 74 63 68 20 6d        [scratch m
b8f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
b900: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 36 7d  ..**.** {H14156}
b910: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
b920: 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ll to.**        
b930: 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69    [sqlite3_confi
b940: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
b950: 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 53 2c 5a  G_PAGECACHE],S,Z
b960: 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ,N).**          
b970: 77 68 65 72 65 20 5a 20 61 6e 64 20 4e 20 61 72  where Z and N ar
b980: 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 69  e non-negative i
b990: 6e 74 65 67 65 72 73 20 61 6e 64 20 0a 2a 2a 20  ntegers and .** 
b9a0: 20 20 20 20 20 20 20 20 20 53 20 69 73 20 61 20           S is a 
b9b0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 6c  pointer to an al
b9c0: 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
b9d0: 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 74 68 61  fer not less tha
b9e0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5a 2a  n.**          Z*
b9f0: 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  N bytes in size 
ba00: 73 68 61 6c 6c 20 63 61 75 73 65 20 53 20 74 6f  shall cause S to
ba10: 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65 0a   be used by the.
ba20: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 61 67  **          [pag
ba30: 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ecache memory al
ba40: 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 61 73 20  locator] for as 
ba50: 6d 61 6e 79 20 61 73 20 4e 20 73 69 6d 75 6c 61  many as N simula
ba60: 74 61 6e 65 6f 75 73 0a 2a 2a 20 20 20 20 20 20  taneous.**      
ba70: 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20      allocations 
ba80: 65 61 63 68 20 6f 66 20 73 69 7a 65 20 28 5a 20  each of size (Z 
ba90: 26 20 7e 37 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  & ~7)..**.** {H1
baa0: 34 31 35 39 7d 20 41 20 73 75 63 63 65 73 73 66  4159} A successf
bab0: 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20  ul call to.**   
bac0: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
bad0: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
bae0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
baf0: 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20  ],S,Z,N).**     
bb00: 20 20 20 20 20 77 68 65 72 65 20 53 20 69 73 20       where S is 
bb10: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  a NULL pointer s
bb20: 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65  hall disable the
bb30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 61  .**          [pa
bb40: 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  gecache memory a
bb50: 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a  llocator]..**.**
bb60: 20 7b 48 31 34 31 36 32 7d 20 41 20 73 75 63 63   {H14162} A succ
bb70: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
bb80: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
bb90: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
bba0: 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20  EAP],H,Z,N).**  
bbb0: 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a 20          where Z 
bbc0: 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65  and N are non-ne
bbd0: 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 20  gative integers 
bbe0: 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  and .**         
bbf0: 20 48 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20   H is a pointer 
bc00: 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d 65  to an aligned me
bc10: 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 20  mory buffer not 
bc20: 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20  less than.**    
bc30: 20 20 20 20 20 20 5a 20 62 79 74 65 73 20 69 6e        Z bytes in
bc40: 20 73 69 7a 65 20 73 68 61 6c 6c 20 65 6e 61 62   size shall enab
bc50: 6c 65 20 74 68 65 20 5b 6d 65 6d 73 79 73 35 5d  le the [memsys5]
bc60: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
bc70: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  r.**          an
bc80: 64 20 63 61 75 73 65 20 69 74 20 74 6f 20 75 73  d cause it to us
bc90: 65 20 62 75 66 66 65 72 20 53 20 61 73 20 69 74  e buffer S as it
bca0: 73 20 6d 65 6d 6f 72 79 20 73 6f 75 72 63 65 20  s memory source 
bcb0: 61 6e 64 20 74 6f 20 75 73 65 0a 2a 2a 20 20 20  and to use.**   
bcc0: 20 20 20 20 20 20 20 61 20 6d 69 6e 69 6d 75 6d         a minimum
bcd0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
bce0: 20 6f 66 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   of N..**.** {H1
bcf0: 34 31 36 35 7d 20 41 20 73 75 63 63 65 73 73 66  4165} A successf
bd00: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
bd10: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
bd20: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
bd30: 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20  ,H,Z,N).**      
bd40: 20 20 20 20 77 68 65 72 65 20 48 20 69 73 20 61      where H is a
bd50: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73 68   NULL pointer sh
bd60: 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65 0a  all disable the.
bd70: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 6d 65 6d  **          [mem
bd80: 73 79 73 35 5d 20 6d 65 6d 6f 72 79 20 61 6c 6c  sys5] memory all
bd90: 6f 63 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ocator..**.** {H
bda0: 31 34 31 36 38 7d 20 41 20 73 75 63 63 65 73 73  14168} A success
bdb0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
bdc0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
bdd0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
bde0: 41 53 49 44 45 5d 2c 5a 2c 4e 29 0a 2a 2a 20 20  ASIDE],Z,N).**  
bdf0: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 63 61          shall ca
be00: 75 73 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  use the default 
be10: 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
be20: 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
be30: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 20 20  figuration.**   
be40: 20 20 20 20 20 20 20 66 6f 72 20 6e 65 77 20 5b         for new [
be50: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
be60: 69 6f 6e 73 5d 20 74 6f 20 62 65 20 4e 20 73 6c  ions] to be N sl
be70: 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73 20 65  ots of Z bytes e
be80: 61 63 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ach..*/.SQLITE_E
be90: 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
bea0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
beb0: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
bec0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
bed0: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
bee0: 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 32  nnections  {H142
bef0: 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20  00} <S20000>.** 
bf00: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
bf10: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
bf20: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
bf30: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
bf40: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
bf50: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
bf60: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
bf70: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
bf80: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
bf90: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
bfa0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
bfb0: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
bfc0: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
bfd0: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
bfe0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
bff0: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
c000: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
c010: 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  ).  The.** sqlit
c020: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
c030: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c  nterface can onl
c040: 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69  y be used immedi
c050: 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74  ately after.** t
c060: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
c070: 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  ection is create
c080: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c090: 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _open()],.** [sq
c0a0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
c0b0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
c0c0: 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a  n_v2()].  .**.**
c0d0: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
c0e0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c0f0: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
c100: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  .)  is the.** co
c110: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
c120: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
c130: 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  de that indicate
c140: 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74  s what.** aspect
c150: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
c160: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
c170: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
c180: 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63  d..** The only c
c190: 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76  hoice for this v
c1a0: 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  alue is [SQLITE_
c1b0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
c1c0: 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62  DE]..** New verb
c1d0: 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
c1e0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
c1f0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
c200: 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69  QLite..** Additi
c210: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64  onal arguments d
c220: 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72  epend on the ver
c230: 62 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  b..**.** INVARIA
c240: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32  NTS:.**.** {H142
c250: 30 33 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  03} A call to [s
c260: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c270: 28 44 2c 56 2c 2e 2e 2e 29 5d 20 73 68 61 6c 6c  (D,V,...)] shall
c280: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
c290: 4f 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  OK].**          
c2a0: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
c2b0: 68 65 20 63 61 6c 6c 20 69 73 20 73 75 63 63 65  he call is succe
c2c0: 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ssful..**.** {H1
c2d0: 34 32 30 36 7d 20 49 66 20 6f 6e 65 20 6f 72 20  4206} If one or 
c2e0: 6d 6f 72 65 20 73 6c 6f 74 73 20 6f 66 20 74 68  more slots of th
c2f0: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  e [lookaside mem
c300: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66  ory allocator] f
c310: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
c320: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c330: 69 6f 6e 5d 20 44 20 61 72 65 20 69 6e 20 75 73  ion] D are in us
c340: 65 2c 20 74 68 65 6e 20 61 20 63 61 6c 6c 20 74  e, then a call t
c350: 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
c360: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c370: 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ](D,[SQLITE_DBCO
c380: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
c390: 2e 2e 2e 29 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  ...) shall.**   
c3a0: 20 20 20 20 20 20 20 66 61 69 6c 20 77 69 74 68         fail with
c3b0: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59   an [SQLITE_BUSY
c3c0: 5d 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0a 2a  ] return code..*
c3d0: 2a 0a 2a 2a 20 7b 48 31 34 32 30 39 7d 20 41 20  *.** {H14209} A 
c3e0: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
c3f0: 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  to .**          
c400: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
c410: 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42  ig](D,[SQLITE_DB
c420: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
c430: 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a  ],B,Z,N) where.*
c440: 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73 20  *          D is 
c450: 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  an open [databas
c460: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
c470: 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 70 6f  d Z and N are po
c480: 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  sitive.**       
c490: 20 20 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20     integers and 
c4a0: 42 20 69 73 20 61 6e 20 61 6c 69 67 6e 65 64 20  B is an aligned 
c4b0: 62 75 66 66 65 72 20 61 74 20 6c 65 61 73 74 20  buffer at least 
c4c0: 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  Z*N bytes in siz
c4d0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  e.**          sh
c4e0: 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 5b 6c  all cause the [l
c4f0: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
c500: 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44  allocator] for D
c510: 20 74 6f 20 75 73 65 20 62 75 66 66 65 72 20 42   to use buffer B
c520: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69   .**          wi
c530: 74 68 20 4e 20 73 6c 6f 74 73 20 6f 66 20 5a 20  th N slots of Z 
c540: 62 79 74 65 73 20 65 61 63 68 2e 0a 2a 2a 0a 2a  bytes each..**.*
c550: 2a 20 7b 48 31 34 32 31 32 7d 20 41 20 73 75 63  * {H14212} A suc
c560: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
c570: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
c580: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 5d  lite3_db_config]
c590: 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  (D,[SQLITE_DBCON
c5a0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42  FIG_LOOKASIDE],B
c5b0: 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a 2a 20 20  ,Z,N) where.**  
c5c0: 20 20 20 20 20 20 20 20 44 20 69 73 20 61 6e 20          D is an 
c5d0: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
c5e0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5a  onnection] and Z
c5f0: 20 61 6e 64 20 4e 20 61 72 65 20 70 6f 73 69 74   and N are posit
c600: 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
c610: 69 6e 74 65 67 65 72 73 20 61 6e 64 20 42 20 69  integers and B i
c620: 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  s NULL pointer s
c630: 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 0a 2a  hall cause the.*
c640: 2a 20 20 20 20 20 20 20 20 20 20 5b 6c 6f 6f 6b  *          [look
c650: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
c660: 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44 20 74 6f  ocator] for D to
c670: 20 61 20 6f 62 74 61 69 6e 20 5a 2a 4e 20 62 79   a obtain Z*N by
c680: 74 65 20 62 75 66 66 65 72 0a 2a 2a 20 20 20 20  te buffer.**    
c690: 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 70        from the p
c6a0: 72 69 6d 61 72 79 20 6d 65 6d 6f 72 79 20 61 6c  rimary memory al
c6b0: 6c 6f 63 61 74 6f 72 20 61 6e 64 20 75 73 65 20  locator and use 
c6c0: 74 68 61 74 20 62 75 66 66 65 72 0a 2a 2a 20 20  that buffer.**  
c6d0: 20 20 20 20 20 20 20 20 77 69 74 68 20 4e 20 6c          with N l
c6e0: 6f 6f 6b 61 73 69 64 65 20 73 6c 6f 74 73 20 6f  ookaside slots o
c6f0: 66 20 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a  f Z bytes each..
c700: 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31 35 7d 20 41  **.** {H14215} A
c710: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
c720: 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   to .**         
c730: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
c740: 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44  fig](D,[SQLITE_D
c750: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
c760: 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a  E],B,Z,N) where.
c770: 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73  **          D is
c780: 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61   an open [databa
c790: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
c7a0: 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 7a  nd Z and N are z
c7b0: 65 72 6f 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20  ero shall.**    
c7c0: 20 20 20 20 20 20 64 69 73 61 62 6c 65 20 74 68        disable th
c7d0: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  e [lookaside mem
c7e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66  ory allocator] f
c7f0: 6f 72 20 44 2e 0a 2a 2a 0a 2a 2a 0a 2a 2f 0a 53  or D..**.**.*/.S
c800: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
c810: 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  AL int sqlite3_d
c820: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
c830: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
c840: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c850: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
c860: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31  ion Routines {H1
c870: 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a  0155} <S20120>.*
c880: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
c890: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
c8a0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
c8b0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
c8c0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
c8d0: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
c8e0: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
c8f0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
c900: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
c910: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
c920: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
c930: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
c940: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
c950: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
c960: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
c970: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
c980: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
c990: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
c9a0: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
c9b0: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
c9c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
c9d0: 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74  LLOC].  By creat
c9e0: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
c9f0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
ca00: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
ca10: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
ca20: 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f  fig()] during co
ca30: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a  nfiguration, an.
ca40: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  ** application c
ca50: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
ca60: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
ca70: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
ca80: 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c  ystem.** for SQL
ca90: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
caa0: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
cab0: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
cac0: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
cad0: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
cae0: 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  h a built-in mem
caf0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
cb00: 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74  at is.** perfect
cb10: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
cb20: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
cb30: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
cb40: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
cb50: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
cb60: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
cb70: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
cb80: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
cb90: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
cba0: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
cbb0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
cbc0: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
cbd0: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
cbe0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
cbf0: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
cc00: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
cc10: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
cc20: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
cc30: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
cc40: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
cc50: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
cc60: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
cc70: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
cc80: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
cc90: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
cca0: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
ccb0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
ccc0: 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64  lloc, xFree, and
ccd0: 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64   xRealloc method
cce0: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
ccf0: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
cd00: 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65  , free(), and re
cd10: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e  alloc() function
cd20: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
cd30: 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ard library..**.
cd40: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
cd50: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
cd60: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
cd70: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
cd80: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
cd90: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
cda0: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
cdb0: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
cdc0: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
cdd0: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
cde0: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
cdf0: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
ce00: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
ce10: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
ce20: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
ce30: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
ce40: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
ce50: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
ce60: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
ce70: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
ce80: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
ce90: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
cea0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
ceb0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
cec0: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
ced0: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
cee0: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
cef0: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
cf00: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
cf10: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
cf20: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a   power of 2..**.
cf30: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
cf40: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
cf50: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
cf60: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
cf70: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
cf80: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
cf90: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
cfa0: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
cfb0: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
cfc0: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
cfd0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
cfe0: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
cff0: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
d000: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
d010: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
d020: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
d030: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
d040: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
d050: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
d060: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
d070: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
d080: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
d090: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79  xShutdown..*/.ty
d0a0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
d0b0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d0c0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
d0d0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
d0e0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d0f0: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
d100: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
d110: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
d120: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
d130: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
d140: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
d150: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
d160: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
d170: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
d180: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
d190: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
d1a0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
d1b0: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
d1c0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
d1d0: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
d1e0: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
d1f0: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
d200: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
d210: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
d220: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
d230: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
d240: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
d250: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
d260: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
d270: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
d280: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
d290: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
d2a0: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
d2b0: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
d2c0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
d2d0: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
d2e0: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
d2f0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
d300: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
d310: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
d320: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
d330: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
d340: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31  tion Options {H1
d350: 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0160} <S20000>.*
d360: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
d370: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
d380: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
d390: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
d3a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d3b0: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
d3c0: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
d3d0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
d3e0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
d3f0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
d400: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
d410: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d420: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
d430: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
d440: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
d450: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
d460: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d470: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
d480: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
d490: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
d4a0: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
d4b0: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
d4c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d4d0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
d4e0: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
d4f0: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
d500: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
d510: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
d520: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
d530: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
d540: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
d550: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
d560: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d570: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
d580: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
d590: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d5a0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
d5b0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
d5c0: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
d5d0: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
d5e0: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e  on.  This option
d5f0: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
d600: 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
d610: 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
d620: 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
d630: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
d640: 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
d650: 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  hread.</dd>.**.*
d660: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d670: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
d680: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
d690: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
d6a0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
d6b0: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
d6c0: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
d6d0: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
d6e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
d6f0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
d700: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
d710: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
d720: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
d730: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
d740: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
d750: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d760: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
d770: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
d780: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
d790: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
d7a0: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
d7b0: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
d7c0: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
d7d0: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
d7e0: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
d7f0: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
d800: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
d810: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
d820: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d830: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
d840: 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65 20 5b  time.  See the [
d850: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 0a  threading mode].
d860: 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  ** documentation
d870: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
d880: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64  information.</dd
d890: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d8a0: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
d8b0: 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
d8c0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
d8d0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
d8e0: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
d8f0: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
d900: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
d910: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
d920: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
d930: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
d940: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
d950: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
d960: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
d970: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
d980: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
d990: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
d9a0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d9b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
d9c0: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
d9d0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
d9e0: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
d9f0: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
da00: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
da10: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
da20: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
da30: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
da40: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
da50: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
da60: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
da70: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
da80: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
da90: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
daa0: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
dab0: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
dac0: 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  ..** See the [th
dad0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
dae0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
daf0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
db00: 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  mation.</dd>.**.
db10: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
db20: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
db30: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
db40: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
db50: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
db60: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
db70: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
db80: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
db90: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
dba0: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
dbb0: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
dbc0: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
dbd0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
dbe0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
dbf0: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
dc00: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
dc10: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
dc20: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
dc30: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
dc40: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
dc50: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
dc60: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
dc70: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
dc80: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
dc90: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
dca0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
dcb0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
dcc0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
dcd0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
dce0: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
dcf0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
dd00: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
dd10: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
dd20: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
dd30: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
dd40: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
dd50: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
dd60: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
dd70: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
dd80: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
dd90: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
dda0: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
ddb0: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
ddc0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ddd0: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
dde0: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
ddf0: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
de00: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
de10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
de20: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
de30: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
de40: 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
de50: 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
de60: 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
de70: 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
de80: 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
de90: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
dea0: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
deb0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
dec0: 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 57  ** statistics. W
ded0: 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68  hen disabled, th
dee0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
def0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
df00: 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65  come .** non-ope
df10: 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
df20: 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
df30: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
df40: 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
df50: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
df60: 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
df70: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
df80: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
df90: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
dfa0: 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
dfb0: 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f  **   </ul>.** </
dfc0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
dfd0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
dfe0: 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
dff0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
e000: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
e010: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
e020: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
e030: 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
e040: 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
e050: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
e060: 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74  ts:  A pointer t
e070: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68  o the memory, th
e080: 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
e090: 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  h scratch buffer
e0a0: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
e0b0: 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72 73  umber of buffers
e0c0: 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a   (N).  The sz.**
e0d0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
e0e0: 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  e a multiple of 
e0f0: 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61 6d  16. The sz param
e100: 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61  eter should be a
e110: 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c 61   few bytes.** la
e120: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61 63  rger than the ac
e130: 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70 61  tual scratch spa
e140: 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65 20  ce required due 
e150: 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61  internal overhea
e160: 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 0a  d..** The first.
e170: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
e180: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
e190: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
e1a0: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
e1b0: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   of memory..** S
e1c0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
e1d0: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  o more than one 
e1e0: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 61  scratch buffer a
e1f0: 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61  t once per threa
e200: 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  d, so.** N shoul
e210: 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20  d be set to the 
e220: 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
e230: 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
e240: 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70  ds.  The sz.** p
e250: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
e260: 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20 73  be 6 times the s
e270: 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
e280: 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
e290: 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63   size..** Scratc
e2a0: 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75 73  h buffers are us
e2b0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
e2c0: 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20  e btree balance 
e2d0: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a  operation.  If.*
e2e0: 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c 61  * The btree bala
e2f0: 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69 74  ncer needs addit
e300: 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79  ional memory bey
e310: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
e320: 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74  ided by.** scrat
e330: 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69 66  ch buffers or if
e340: 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66 66   no scratch buff
e350: 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65 63  er space is spec
e360: 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69  ified, then SQLi
e370: 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73  te.** goes to [s
e380: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
e390: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
e3a0: 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c  emory it needs.<
e3b0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e3c0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
e3d0: 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
e3e0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
e3f0: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
e400: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
e410: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
e420: 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64  use for.** the d
e430: 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
e440: 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
e450: 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ult page cache i
e460: 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a  mplemenation.  .
e470: 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
e480: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
e490: 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
e4a0: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
e4b0: 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
e4c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
e4d0: 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
e4e0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
e4f0: 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a  _PCACHE option..
e500: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
e510: 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
e520: 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70  this option: A p
e530: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
e540: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
e550: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
e560: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
e570: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
e580: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
e590: 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  sz argument must
e5a0: 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74   be a power of t
e5b0: 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
e5c0: 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 20 66  nd 32768.  The f
e5d0: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
e5e0: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
e5f0: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
e600: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
e610: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
e620: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
e630: 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
e640: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
e650: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
e660: 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
e670: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
e680: 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
e690: 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
e6a0: 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 64  to cache.  If ad
e6b0: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
e6c0: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
e6d0: 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
e6e0: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
e6f0: 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
e700: 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
e710: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
e720: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
e730: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
e740: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
e750: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
e760: 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20  n might use one 
e770: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e  or more of the N
e780: 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64   buffers to hold
e790: 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f   .** memory acco
e7a0: 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69  unting informati
e7b0: 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  on. </dd>.**.** 
e7c0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
e7d0: 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
e7e0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
e7f0: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
e800: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
e810: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
e820: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
e830: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
e840: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e850: 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
e860: 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
e870: 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
e880: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
e890: 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
e8a0: 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
e8b0: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
e8c0: 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f   arguments: A po
e8d0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
e8e0: 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ory, the number 
e8f0: 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
e900: 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
e910: 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
e920: 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
e930: 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66 69  e.  If.** the fi
e940: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
e950: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
e960: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
e970: 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
e980: 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
e990: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
e9a0: 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
e9b0: 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
e9c0: 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
e9d0: 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
e9e0: 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
e9f0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
ea00: 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a  ALLOC].  If the.
ea10: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
ea20: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
ea30: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
ea40: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
ea50: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
ea60: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
ea70: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
ea80: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
ea90: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
eaa0: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
eab0: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
eac0: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
ead0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
eae0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
eaf0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
eb00: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
eb10: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
eb20: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
eb30: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
eb40: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
eb50: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
eb60: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
eb70: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
eb80: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
eb90: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
eba0: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
ebb0: 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
ebc0: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
ebd0: 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
ebe0: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
ebf0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
ec00: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
ec10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
ec20: 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
ec30: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
ec40: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
ec50: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
ec60: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
ec70: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
ec80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
ec90: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
eca0: 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
ecb0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
ecc0: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
ecd0: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
ece0: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
ecf0: 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
ed00: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20  utines..** This 
ed10: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
ed20: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
ed30: 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
ed40: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
ed50: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
ed60: 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
ed70: 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
ed80: 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
ed90: 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
eda0: 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
edb0: 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ample.</dd>.**.*
edc0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
edd0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
ede0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
edf0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
ee00: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
ee10: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66  etermine the def
ee20: 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  ault.** memory a
ee30: 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69  llcation lookasi
ee40: 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e  de optimization.
ee50: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
ee60: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
ee70: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
ee80: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
ee90: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
eea0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
eeb0: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
eec0: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
eed0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
eee0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
eef0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
ef00: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
ef10: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
ef20: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
ef30: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
ef40: 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61   pointer to.** a
ef50: 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
ef60: 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
ef70: 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
ef80: 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
ef90: 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
efa0: 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
efb0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
efc0: 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  .  SQLite makes 
efd0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
efe0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73   object and uses
eff0: 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63   it for page cac
f000: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
f010: 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  tions.</dd>.**.*
f020: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
f030: 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64  FIG_GETPCACHE</d
f040: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
f050: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
f060: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
f070: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
f080: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
f090: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
f0a0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  s] object.  SQLi
f0b0: 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65  te copies of the
f0c0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65   current.** page
f0d0: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
f0e0: 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
f0f0: 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
f100: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
f110: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
f120: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
f130: 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
f140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
f150: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
f160: 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
f170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f180: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
f190: 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
f1a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f1b0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
f1c0: 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
f1d0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
f1e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f1f0: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
f200: 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
f210: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
f220: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f230: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
f240: 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
f250: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
f260: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
f270: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
f280: 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
f290: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
f2a0: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
f2b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
f2c0: 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
f2d0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
f2e0: 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
f2f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f300: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
f310: 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
f320: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f330: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
f340: 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
f350: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
f360: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
f370: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
f380: 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
f390: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
f3a0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
f3b0: 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
f3c0: 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
f3d0: 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
f3e0: 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
f3f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f400: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
f410: 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
f420: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f430: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
f440: 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c        14  /* sql
f450: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
f460: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
f470: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
f480: 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f  TPCACHE    15  /
f490: 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
f4a0: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a  _methods* */../*
f4b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
f4c0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
f4d0: 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c 53 32  ons {H10170} <S2
f4e0: 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0000>.** EXPERIM
f4f0: 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ENTAL.**.** Thes
f500: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
f510: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
f520: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
f530: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
f540: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
f550: 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
f560: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
f570: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
f580: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
f590: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
f5a0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
f5b0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
f5c0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
f5d0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
f5e0: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
f5f0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
f600: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
f610: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
f620: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
f630: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
f640: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
f650: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
f660: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
f670: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
f680: 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
f690: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
f6a0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
f6b0: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
f6c0: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
f6d0: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
f6e0: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
f6f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f700: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
f710: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
f720: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
f730: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
f740: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
f750: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
f760: 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
f770: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
f780: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
f790: 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
f7a0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
f7b0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
f7c0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
f7d0: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
f7e0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f7f0: 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
f800: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
f810: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
f820: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
f830: 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
f840: 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
f850: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 20  kaside memory.  
f860: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
f870: 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c  ument may be NUL
f880: 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
f890: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
f8a0: 63 61 74 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  cate the lookasi
f8b0: 64 65 0a 2a 2a 20 62 75 66 66 65 72 20 69 74 73  de.** buffer its
f8c0: 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
f8d0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54  e3_malloc()].  T
f8e0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
f8f0: 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
f900: 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
f910: 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
f920: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 61 72  and the third ar
f930: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
f940: 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
f950: 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
f960: 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
f970: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
f980: 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
f990: 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
f9a0: 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
f9b0: 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
f9c0: 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
f9d0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  s.</dd>.**.** </
f9e0: 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
f9f0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
fa00: 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31  OOKASIDE    1001
fa10: 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
fa20: 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt */.../*.** CA
fa30: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
fa40: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
fa50: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
fa60: 7b 48 31 32 32 30 30 7d 20 3c 53 31 30 37 30 30  {H12200} <S10700
fa70: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
fa80: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
fa90: 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
faa0: 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
fab0: 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
fac0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
fad0: 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
fae0: 66 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78  f SQLite. The ex
faf0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
fb00: 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
fb10: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
fb20: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
fb30: 6d 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73  mpatibility cons
fb40: 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  iderations..**.*
fb50: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
fb60: 0a 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45 61 63  .** {H12201} Eac
fb70: 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20  h new [database 
fb80: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c  connection] shal
fb90: 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20 20  l have the.**   
fba0: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
fbb0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
fbc0: 65 61 74 75 72 65 20 64 69 73 61 62 6c 65 64 20  eature disabled 
fbd0: 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
fbe0: 2a 20 7b 48 31 32 32 30 32 7d 20 54 68 65 20 5b  * {H12202} The [
fbf0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
fc00: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c  _result_codes(D,
fc10: 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  F)] interface sh
fc20: 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20  all enable.**   
fc30: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
fc40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
fc50: 6f 72 20 74 68 65 20 20 5b 64 61 74 61 62 61 73  or the  [databas
fc60: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
fc70: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74  **          if t
fc80: 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 20 69  he F parameter i
fc90: 73 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62  s true, or disab
fca0: 6c 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20  le them if F is 
fcb0: 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  false..*/.int sq
fcc0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
fcd0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
fce0: 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
fcf0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fd00: 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
fd10: 6f 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c 53  owid {H12220} <S
fd20: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63  10700>.**.** Eac
fd30: 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
fd40: 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
fd50: 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
fd60: 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
fd70: 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
fd80: 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
fd90: 5d 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73 20  ]. The rowid is 
fda0: 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
fdb0: 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
fdc0: 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
fdd0: 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
fde0: 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
fdf0: 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
fe00: 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
fe10: 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
fe20: 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
fe30: 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20 74  mns. If.** the t
fe40: 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
fe50: 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
fe60: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
fe70: 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
fe80: 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
fe90: 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
fea0: 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  id..**.** This r
feb0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
fec0: 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
fed0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
fee0: 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
fef0: 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61  ERT] into the da
ff00: 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20  tabase from the 
ff10: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ff20: 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
ff30: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20  first argument. 
ff40: 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75   If no successfu
ff50: 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
ff60: 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
ff70: 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
ff80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
ff90: 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
ffa0: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 5b 49 4e  .**.** If an [IN
ffb0: 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
ffc0: 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74  hin a trigger, t
ffd0: 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  hen the [rowid] 
ffe0: 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
fff0: 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e  ** row is return
10000 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
10010 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ne as long as th
10020 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e  e trigger is run
10030 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
10040 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65  e the trigger te
10050 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61  rminates, the va
10060 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
10070 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
10080 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c  reverts to the l
10090 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74  ast value insert
100a0 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  ed before the tr
100b0 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a  igger fired..**.
100c0 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  ** An [INSERT] t
100d0 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
100e0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
100f0 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
10100 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
10110 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
10120 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
10130 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
10140 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
10150 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20  e.  Thus INSERT 
10160 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
10170 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
10180 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
10190 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
101a0 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
101b0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
101c0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
101d0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
101e0 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
101f0 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49  n fails.  When I
10200 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
10210 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
10220 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
10230 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
10240 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
10250 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
10260 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
10270 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
10280 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
10290 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
102a0 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
102b0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
102c0 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
102d0 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
102e0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
102f0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46  terface..**.** F
10300 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
10310 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
10320 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
10330 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
10340 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
10350 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
10360 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
10370 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   back..**.** INV
10380 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
10390 48 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c  H12221} The [sql
103a0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
103b0 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69  _rowid()] functi
103c0 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a  on shall return.
103d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
103e0 5b 72 6f 77 69 64 5d 0a 2a 2a 20 20 20 20 20 20  [rowid].**      
103f0 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73 74 20      of the most 
10400 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
10410 6c 20 5b 49 4e 53 45 52 54 5d 20 70 65 72 66 6f  l [INSERT] perfo
10420 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61 6d 65  rmed on the same
10430 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
10440 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10450 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68  n] and within th
10460 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72  e same or higher
10470 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20   level.**       
10480 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65     trigger conte
10490 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74  xt, or zero if t
104a0 68 65 72 65 20 68 61 76 65 20 62 65 65 6e 20 6e  here have been n
104b0 6f 20 71 75 61 6c 69 66 79 69 6e 67 0a 2a 2a 20  o qualifying.** 
104c0 20 20 20 20 20 20 20 20 20 5b 49 4e 53 45 52 54           [INSERT
104d0 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
104e0 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20 54 68 65  .** {H12223} The
104f0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
10500 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66  nsert_rowid()] f
10510 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65  unction shall re
10520 74 75 72 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  turn the.**     
10530 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20       same value 
10540 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
10550 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
10560 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20  r context.**    
10570 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c        immediatel
10580 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74  y before and aft
10590 65 72 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  er a [ROLLBACK].
105a0 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
105b0 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 33  NS:.**.** {A1223
105c0 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65  2} If a separate
105d0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
105e0 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
105f0 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  on the same.**  
10600 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
10610 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
10620 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
10630 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
10640 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
10650 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
10660 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
10670 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
10680 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
10690 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
106a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
106b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
106c0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
106d0 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
106e0 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20    unpredictable 
106f0 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
10700 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
10710 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
10720 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20 69            last i
10730 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
10740 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
10750 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
10760 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
10770 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
10780 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
10790 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
107a0 6f 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d  odified {H12240}
107b0 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10600>.**.** 
107c0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
107d0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
107e0 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
107f0 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
10800 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
10810 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
10820 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
10830 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
10840 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
10850 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
10860 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
10870 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
10880 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
10890 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
108a0 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
108b0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
108c0 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
108d0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
108e0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
108f0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
10900 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
10910 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
10920 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  rs are not count
10930 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
10940 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
10950 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  es()] function.*
10960 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  * to find the to
10970 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
10980 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  anges including 
10990 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
109a0 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a  y triggers..**.*
109b0 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  * A "row change"
109c0 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
109d0 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
109e0 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
109f0 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
10a00 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
10a10 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
10a20 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
10a30 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
10a40 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
10a50 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
10a60 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
10a70 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
10a80 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44  RT processing, D
10a90 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79  ROP TABLE, or by
10aa0 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   any other.** me
10ab0 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20  chanisms do not 
10ac0 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20  count as direct 
10ad0 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
10ae0 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f  ** A "trigger co
10af0 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70  ntext" is a scop
10b00 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74  e of execution t
10b10 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a  hat begins and.*
10b20 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20  * ends with the 
10b30 73 63 72 69 70 74 20 6f 66 20 61 20 74 72 69 67  script of a trig
10b40 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73  ger.  Most SQL s
10b50 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
10b60 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
10b70 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
10b80 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
10b90 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
10ba0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
10bb0 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
10bc0 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
10bd0 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
10be0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
10bf0 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
10c00 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
10c10 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
10c20 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
10c30 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
10c40 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
10c50 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43  uration..**.** C
10c60 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
10c70 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
10c80 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
10c90 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
10ca0 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
10cb0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
10cc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
10cd0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
10ce0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
10cf0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
10d00 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
10d10 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
10d20 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
10d30 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
10d40 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
10d50 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
10d60 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61  ** Thus, when ca
10d70 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
10d80 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
10d90 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
10da0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
10db0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
10dc0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
10dd0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
10de0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
10df0 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
10e00 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69  e top level.  Wi
10e10 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
10e20 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
10e30 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
10e40 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
10e50 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
10e60 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
10e70 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
10e80 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
10e90 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
10ea0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
10eb0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
10ec0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
10ed0 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
10ee0 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
10ef0 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
10f00 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
10f10 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
10f20 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
10f30 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
10f40 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
10f50 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a  r own context..*
10f60 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
10f70 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61  ements the comma
10f80 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  nd "DELETE FROM 
10f90 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61  table" without a
10fa0 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a   WHERE clause.**
10fb0 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64   by dropping and
10fc0 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20   recreating the 
10fd0 74 61 62 6c 65 2e 20 20 44 6f 69 6e 67 20 73 6f  table.  Doing so
10fe0 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20   is much faster 
10ff0 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68  than going.** th
11000 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69  rough and deleti
11010 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c  ng individual el
11020 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20  ements from the 
11030 74 61 62 6c 65 2e 20 20 42 65 63 61 75 73 65 20  table.  Because 
11040 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d  of this.** optim
11050 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c  ization, the del
11060 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54  etions in "DELET
11070 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72  E FROM table" ar
11080 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65  e not row change
11090 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f  s and.** will no
110a0 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20  t be counted by 
110b0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
110c0 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65  ges() or [sqlite
110d0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
110e0 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c  )].** functions,
110f0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
11100 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
11110 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
11120 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e  originally.** in
11130 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20   the table.  To 
11140 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
11150 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
11160 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
11170 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
11180 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
11190 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
111a0 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75    Or recompile u
111b0 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
111c0 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54  ITE_OMIT_TRUNCAT
111d0 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20  E_OPTIMIZATION] 
111e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
111f0 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ion to disable t
11200 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  he.** optimizati
11210 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65  on on all querie
11220 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
11230 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  NTS:.**.** {H122
11240 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
11250 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
11260 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72  tion shall retur
11270 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  n the number of.
11280 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 20  **          row 
11290 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
112a0 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
112b0 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
112c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
112d0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
112e0 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  t on the same da
112f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11300 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  n and.**        
11310 20 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d    within the sam
11320 65 20 6f 72 20 68 69 67 68 65 72 20 74 72 69 67  e or higher trig
11330 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20  ger context, or 
11340 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61  zero if there ha
11350 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ve.**          n
11360 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c  ot been any qual
11370 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67  ifying row chang
11380 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34  es..**.** {H1224
11390 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66  3} Statements of
113a0 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54   the form "DELET
113b0 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65  E FROM tablename
113c0 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20  " with no.**    
113d0 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 75        WHERE clau
113e0 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73  se shall cause s
113f0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
11400 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
11410 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
11420 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72  )] to return zer
11430 6f 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  o, regardless of
11440 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
11450 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
11460 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68  originally in th
11470 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41  e table..**.** A
11480 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
11490 2a 20 7b 41 31 32 32 35 32 7d 20 49 66 20 61 20  * {A12252} If a 
114a0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
114b0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
114c0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
114d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
114e0 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 20            while 
114f0 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
11500 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
11510 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
11520 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  turned.**       
11530 20 20 20 69 73 20 75 6e 70 72 65 64 69 63 74 61     is unpredicta
11540 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
11550 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
11560 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
11570 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
11580 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
11590 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
115a0 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 36 30  Modified {H12260
115b0 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10600>.**.**
115c0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
115d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
115e0 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
115f0 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52   caused by INSER
11600 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20  T,.** UPDATE or 
11610 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
11620 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
11630 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11640 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
11650 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75   The count inclu
11660 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20  des all changes 
11670 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72  from all trigger
11680 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65   contexts.  Howe
11690 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
116a0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
116b0 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
116c0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50  to implement REP
116d0 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73  LACE constraints
116e0 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b  ,.** do rollback
116f0 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65  s or ABORT proce
11700 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74  ssing, or DROP t
11710 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e  able processing.
11720 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20  .** The changes 
11730 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73  are counted as s
11740 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65  oon as the state
11750 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
11760 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c  them is.** compl
11770 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73  eted (when the s
11780 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
11790 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
117a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
117b0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
117c0 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a  nalize()])..**.*
117d0 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
117e0 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
117f0 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
11800 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48  le" without a WH
11810 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79  ERE clause.** by
11820 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
11830 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
11840 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75  le.  (This is mu
11850 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67  ch faster than g
11860 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20  oing.** through 
11870 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64  and deleting ind
11880 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73  ividual elements
11890 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e   from the table.
118a0 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  )  Because of th
118b0 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69  is.** optimizati
118c0 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e  on, the deletion
118d0 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f  s in "DELETE FRO
118e0 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74  M table" are not
118f0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64   row changes and
11900 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  .** will not be 
11910 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73  counted by the s
11920 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
11930 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   or [sqlite3_tot
11940 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a  al_changes()].**
11950 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61   functions, rega
11960 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75  rdless of the nu
11970 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73  mber of elements
11980 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69   that were origi
11990 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20  nally.** in the 
119a0 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61  table.  To get a
119b0 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74  n accurate count
119c0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
119d0 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20  f rows deleted, 
119e0 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46  use.** "DELETE F
119f0 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20  ROM table WHERE 
11a00 31 22 20 69 6e 73 74 65 61 64 2e 20 20 20 4f 72  1" instead.   Or
11a10 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67   recompile using
11a20 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
11a30 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50  OMIT_TRUNCATE_OP
11a40 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70  TIMIZATION] comp
11a50 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11a60 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a  to disable the.*
11a70 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f  * optimization o
11a80 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a  n all queries..*
11a90 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
11aa0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
11ab0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
11ac0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
11ad0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 31  S:.**.** {H12261
11ae0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  } The [sqlite3_t
11af0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
11b00 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61  returns the tota
11b10 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20  l number.**     
11b20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68 61 6e       of row chan
11b30 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e  ges caused by IN
11b40 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e  SERT, UPDATE, an
11b50 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20  d/or DELETE.**  
11b60 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
11b70 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ts on the same [
11b80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11b90 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20  ion], in any.** 
11ba0 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72           trigger
11bb0 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20   context, since 
11bc0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
11bd0 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72 65 61  nection was crea
11be0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ted..**.** {H122
11bf0 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f  63} Statements o
11c00 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45  f the form "DELE
11c10 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d  TE FROM tablenam
11c20 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20  e" with no.**   
11c30 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61         WHERE cla
11c40 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68  use shall not ch
11c50 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
11c60 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20  eturned.**      
11c70 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
11c80 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
11c90 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
11ca0 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32  ONS:.**.** {A122
11cb0 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  64} If a separat
11cc0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
11cd0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
11ce0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
11cf0 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
11d00 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
11d10 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
11d20 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
11d30 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
11d40 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65           returne
11d50 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
11d60 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
11d70 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
11d80 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
11d90 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
11da0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11db0 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
11dc0 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b  -Running Query {
11dd0 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e  H12270} <S30500>
11de0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
11df0 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
11e00 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
11e10 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
11e20 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
11e30 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
11e40 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
11e50 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
11e60 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
11e70 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
11e80 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
11e90 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
11ea0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
11eb0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
11ec0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
11ed0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
11ee0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
11ef0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
11f00 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63   It is safe to c
11f10 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
11f20 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
11f30 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
11f40 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
11f50 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
11f60 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
11f70 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
11f80 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
11f90 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
11fa0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
11fb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11fc0 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
11fd0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
11fe0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
11ff0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12000 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
12010 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72  * If an SQL oper
12020 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
12030 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
12040 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
12050 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
12060 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
12070 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
12080 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
12090 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
120a0 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
120b0 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
120c0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
120d0 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61  .** An SQL opera
120e0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
120f0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
12100 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
12110 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74  ERRUPT]..** If t
12120 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
12130 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
12140 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
12150 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
12160 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
12170 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
12180 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
12190 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
121a0 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
121b0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
121c0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
121d0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
121e0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68 61  3_interrupt() ha
121f0 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
12200 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
12210 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
12220 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
12230 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
12240 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  rns..**.** INVAR
12250 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
12260 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2271} The [sqlit
12270 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20  e3_interrupt()] 
12280 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66  interface will f
12290 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67  orce all running
122a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
122b0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
122c0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
122d0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
122e0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
122f0 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74       to halt aft
12300 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74  er processing at
12310 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69   most one additi
12320 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61 74 61  onal row of data
12330 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 32 7d  ..**.** {H12272}
12340 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
12350 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  nt that is inter
12360 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74  rupted by [sqlit
12370 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
12380 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
12390 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
123a0 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a  INTERRUPT]..**.*
123b0 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
123c0 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20 49 66  *.** {A12279} If
123d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
123e0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
123f0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
12400 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20  nterrupt()].**  
12410 20 20 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69          is runni
12420 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
12430 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
12440 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
12450 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12460 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
12470 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
12480 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
12490 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
124a0 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20  mplete {H10510} 
124b0 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70200>.**.** T
124c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
124d0 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d  e useful for com
124e0 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
124f0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
12500 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
12510 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
12520 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70  ems to form comp
12530 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74 65  lete a SQL state
12540 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
12550 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
12560 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
12570 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
12580 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
12590 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68  for parsing.  Th
125a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
125b0 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
125c0 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
125d0 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
125e0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
125f0 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65  tement.  A state
12600 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
12610 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
12620 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
12630 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
12640 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
12650 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a  fragment of a.**
12660 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
12670 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69  statement.  Semi
12680 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
12690 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
126a0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
126b0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
126c0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
126d0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
126e0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
126f0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
12700 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
12710 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
12720 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
12730 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
12740 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
12750 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
12760 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
12770 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
12780 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
12790 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
127a0 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
127b0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
127c0 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
127d0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
127e0 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d 20 41  **.** {H10511} A
127f0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 61 6c   successful eval
12800 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  uation of [sqlit
12810 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f  e3_complete()] o
12820 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
12830 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
12840 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20 73  6()] functions s
12850 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
12860 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65 72 69   return a numeri
12870 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  c 1 if and only 
12880 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f 6e 2d  if the last non-
12890 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 20 20  whitespace.**   
128a0 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69 6e 20         token in 
128b0 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 20 61  their input is a
128c0 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 20   semicolon that 
128d0 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65  is not in betwee
128e0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
128f0 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20  e BEGIN and END 
12900 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 49 47  of a CREATE TRIG
12910 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  GER statement..*
12920 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20 49 66  *.** {H10512} If
12930 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
12940 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
12950 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e 76 6f  s during an invo
12960 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  cation.**       
12970 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63     of [sqlite3_c
12980 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20 5b 73  omplete()] or [s
12990 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
129a0 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  6()] then the.**
129b0 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e            routin
129c0 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b  e shall return [
129d0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
129e0 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
129f0 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 32 7d  :.**.** {A10512}
12a00 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
12a10 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
12a20 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
12a30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
12a40 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73           UTF-8 s
12a50 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  tring..**.** {A1
12a60 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20  0513} The input 
12a70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
12a80 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
12a90 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
12aa0 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
12ab0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
12ac0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
12ad0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
12ae0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
12af0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
12b00 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
12b10 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
12b20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
12b30 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
12b40 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
12b50 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
12b60 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30  Y Errors {H12310
12b70 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S40400>.**.**
12b80 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65   This routine se
12b90 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
12ba0 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
12bb0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  t be invoked whe
12bc0 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
12bd0 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
12be0 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
12bf0 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  able that anothe
12c00 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
12c10 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
12c20 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
12c30 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
12c40 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
12c50 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
12c60 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
12c70 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
12c80 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
12c90 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
12ca0 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68   the lock. If th
12cb0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
12cc0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
12cd0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
12ce0 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  k will be invoke
12cf0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
12d00 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
12d10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
12d20 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73  o the handler is
12d30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
12d40 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
12d50 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
12d60 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
12d70 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
12d80 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f  ler().  The seco
12d90 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
12da0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61  * the handler ca
12db0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
12dc0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
12dd0 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
12de0 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
12df0 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
12e00 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
12e10 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20   If the.** busy 
12e20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
12e30 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
12e40 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
12e50 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
12e60 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
12e70 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
12e80 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
12e90 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
12ea0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
12eb0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
12ec0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
12ed0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
12ee0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
12ef0 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
12f00 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
12f10 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
12f20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
12f30 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
12f40 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
12f50 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
12f60 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
12f70 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
12f80 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
12f90 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51  ontention. If SQ
12fa0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
12fb0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
12fc0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
12fd0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
12fe0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
12ff0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
13000 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
13010 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
13020 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13030 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
13040 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
13050 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
13060 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
13070 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
13080 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
13090 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
130a0 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
130b0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
130c0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
130d0 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
130e0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
130f0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
13100 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
13110 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
13120 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
13130 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
13140 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
13150 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
13160 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
13170 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
13180 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
13190 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
131a0 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
131b0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
131c0 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
131d0 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
131e0 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
131f0 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
13200 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
13210 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
13220 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
13230 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
13240 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
13250 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
13260 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
13270 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
13280 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
13290 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
132a0 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
132b0 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
132c0 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
132d0 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  oceed..**.** The
132e0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
132f0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
13300 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
13310 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
13320 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
13330 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13340 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
13350 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
13360 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
13370 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
13380 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
13390 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
133a0 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
133b0 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
133c0 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
133d0 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
133e0 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
133f0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
13400 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
13410 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
13420 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
13430 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
13440 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
13450 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
13460 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
13470 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
13480 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
13490 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61  s.  If it is una
134a0 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
134b0 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
134c0 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
134d0 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
134e0 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
134f0 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
13500 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
13510 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
13520 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
13530 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
13540 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
13550 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
13560 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
13570 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72  CKED].  This err
13580 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
13590 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
135a0 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
135b0 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
135c0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
135d0 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
135e0 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
135f0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
13600 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
13610 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
13620 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
13630 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
13640 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
13650 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
13660 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
13670 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
13680 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
13690 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
136a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
136b0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
136c0 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
136d0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
136e0 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
136f0 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f  set handler.  No
13700 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
13710 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
13720 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
13730 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
13740 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
13750 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
13760 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
13770 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
13780 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
13790 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
137a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
137b0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
137c0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
137d0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
137e0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
137f0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
13800 72 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49  r..** .** INVARI
13810 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
13820 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  311} The [sqlite
13830 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
13840 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ,C,A)] function 
13850 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a 2a 2a  shall replace.**
13860 20 20 20 20 20 20 20 20 20 20 62 75 73 79 20 63            busy c
13870 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 20 5b  allback in the [
13880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13890 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 20 6e 65  ion] D with a ne
138a0 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  w.**          a 
138b0 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
138c0 20 43 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69   C and applicati
138d0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
138e0 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 32  A..**.** {H12312
138f0 7d 20 4e 65 77 6c 79 20 63 72 65 61 74 65 64 20  } Newly created 
13900 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13910 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68 61 76  tions] shall hav
13920 65 20 61 20 62 75 73 79 0a 2a 2a 20 20 20 20 20  e a busy.**     
13930 20 20 20 20 20 68 61 6e 64 6c 65 72 20 6f 66 20       handler of 
13940 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  NULL..**.** {H12
13950 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72  314} When two or
13960 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 73 65 20   more [database 
13970 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61  connections] sha
13980 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  re a.**         
13990 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
139a0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20  _shared_cache | 
139b0 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a  common cache],.*
139c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
139d0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
139e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
139f0 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c  nection currentl
13a00 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  y using.**      
13a10 20 20 20 20 74 68 65 20 63 61 63 68 65 20 73 68      the cache sh
13a20 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  all be invoked w
13a30 68 65 6e 20 74 68 65 20 63 61 63 68 65 20 65 6e  hen the cache en
13a40 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e  counters a lock.
13a50 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36 7d 20  .**.** {H12316} 
13a60 49 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  If a busy handle
13a70 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
13a80 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  ns zero, then th
13a90 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
13aa0 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ce.**          t
13ab0 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65  hat provoked the
13ac0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20 73   locking event s
13ad0 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  hall return [SQL
13ae0 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
13af0 20 7b 48 31 32 33 31 38 7d 20 53 51 4c 69 74 65   {H12318} SQLite
13b00 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73 20 74   shall invokes t
13b10 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
13b20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
13b30 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20  ts which.**     
13b40 20 20 20 20 20 61 72 65 20 61 20 63 6f 70 79 20       are a copy 
13b50 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20 73  of the pointer s
13b60 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 33  upplied by the 3
13b70 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
13b80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
13b90 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
13ba0 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74  r()] and a count
13bb0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
13bc0 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20  f prior.**      
13bd0 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20      invocations 
13be0 6f 66 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  of the busy hand
13bf0 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d 65  ler for the same
13c00 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a   locking event..
13c10 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
13c20 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33 31 39  S:.**.** {A12319
13c30 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  } A busy handler
13c40 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
13c50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
13c60 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  nection.**      
13c70 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72 65 64      or [prepared
13c80 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
13c90 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
13ca0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
13cb0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
13cc0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
13cd0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
13ce0 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
13cf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
13d00 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20   A Busy Timeout 
13d10 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34 31 30  {H12340} <S40410
13d20 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
13d30 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
13d40 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
13d50 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
13d60 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
13d70 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
13d80 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
13d90 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
13da0 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e  locked.  The han
13db0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
13dc0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
13dd0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
13de0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
13df0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
13e00 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
13e10 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 74  ed. {H12343} Aft
13e20 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  er "ms" millisec
13e30 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
13e40 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
13e50 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
13e60 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
13e70 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
13e80 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
13e90 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
13ea0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a  OERR_BLOCKED]..*
13eb0 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69  *.** Calling thi
13ec0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
13ed0 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
13ee0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
13ef0 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
13f00 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
13f10 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  lers..**.** Ther
13f20 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
13f30 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
13f40 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
13f50 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
13f60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
13f70 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  y any given mome
13f80 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
13f90 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
13fa0 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
13fb0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
13fc0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
13fd0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
13fe0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
13ff0 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
14000 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
14010 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
14020 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
14030 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  341} The [sqlite
14040 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
14050 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
14060 20 6f 76 65 72 72 69 64 65 20 61 6e 79 20 70 72   override any pr
14070 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ior.**          
14080 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
14090 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c  meout()] or [sql
140a0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
140b0 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20  r()] setting.** 
140c0 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20           on the 
140d0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
140e0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
140f0 2a 20 7b 48 31 32 33 34 33 7d 20 49 66 20 74 68  * {H12343} If th
14100 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
14110 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  to [sqlite3_busy
14120 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c  _timeout()] is l
14130 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  ess than.**     
14140 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f       or equal to
14150 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20   zero, then the 
14160 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61  busy handler sha
14170 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 20 73 6f  ll be cleared so
14180 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
14190 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74    all subsequent
141a0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20   locking events 
141b0 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75  immediately retu
141c0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
141d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 34 7d  ..**.** {H12344}
141e0 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   If the 2nd para
141f0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
14200 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
14210 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a  ] is a positive.
14220 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
14230 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73  er N, then a bus
14240 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20  y handler shall 
14250 62 65 20 73 65 74 20 74 68 61 74 20 72 65 70 65  be set that repe
14260 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20  atedly calls.** 
14270 20 20 20 20 20 20 20 20 20 74 68 65 20 78 53 6c           the xSl
14280 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20  eep() method in 
14290 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
142a0 20 7c 20 56 46 53 20 69 6e 74 65 72 66 61 63 65   | VFS interface
142b0 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20  ] until.**      
142c0 20 20 20 20 65 69 74 68 65 72 20 74 68 65 20 6c      either the l
142d0 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e  ock clears or un
142e0 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69  til the cumulati
142f0 76 65 20 73 6c 65 65 70 20 74 69 6d 65 0a 2a 2a  ve sleep time.**
14300 20 20 20 20 20 20 20 20 20 20 72 65 70 6f 72 74            report
14310 65 64 20 62 61 63 6b 20 62 79 20 78 53 6c 65 65  ed back by xSlee
14320 70 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69  p() exceeds N mi
14330 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69  lliseconds..*/.i
14340 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
14350 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
14360 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
14370 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
14380 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
14390 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
143a0 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20 3c 53  ries {H12370} <S
143b0 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66  10000>.**.** Def
143c0 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
143d0 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
143e0 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
143f0 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
14400 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
14410 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
14420 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
14430 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
14440 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
14450 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
14460 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
14470 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
14480 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
14490 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
144a0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
144b0 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
144c0 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
144d0 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
144e0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
144f0 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
14500 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
14510 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
14520 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
14530 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
14540 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
14550 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
14560 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
14570 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
14580 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
14590 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
145a0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
145b0 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
145c0 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
145d0 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
145e0 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
145f0 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
14600 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
14610 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
14620 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
14630 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
14640 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
14650 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
14660 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
14670 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
14680 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
14690 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
146a0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
146b0 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
146c0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
146d0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
146e0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
146f0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
14700 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
14710 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
14720 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
14730 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
14740 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
14750 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
14760 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
14770 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
14780 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
14790 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
147a0 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
147b0 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
147c0 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
147d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
147e0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73  ble()]..**.** As
147f0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
14800 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
14810 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
14820 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
14830 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
14840 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
14850 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
14860 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
14870 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
14880 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14890 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
148a0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
148b0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
148c0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
148d0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
148e0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
148f0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
14900 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
14910 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
14920 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
14930 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
14940 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
14950 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
14960 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
14970 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
14980 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
14990 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
149a0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
149b0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
149c0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
149d0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
149e0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
149f0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
14a00 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
14a10 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
14a20 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
14a30 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
14a40 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
14a50 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14a60 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
14a70 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
14a80 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
14a90 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14aa0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
14ab0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
14ac0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
14ad0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
14ae0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
14af0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
14b00 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
14b10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
14b20 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
14b30 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
14b40 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
14b50 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
14b60 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
14b70 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
14b80 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
14b90 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
14ba0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
14bb0 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65   It returns a re
14bc0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
14bd0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
14be0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
14bf0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
14c00 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67  fter the calling
14c10 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69   function has fi
14c20 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65  nished using the
14c30 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75   result, it shou
14c40 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70  ld.** pass the p
14c50 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65  ointer to the re
14c60 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71  sult table to sq
14c70 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
14c80 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
14c90 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
14ca0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
14cb0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
14cc0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
14cd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
14ce0 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
14cf0 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
14d00 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
14d10 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
14d20 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
14d30 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
14d40 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
14d50 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
14d60 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14d70 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
14d80 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
14d90 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
14da0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
14db0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14dc0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
14dd0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
14de0 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
14df0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
14e00 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
14e10 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
14e20 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
14e30 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
14e40 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
14e50 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
14e60 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
14e70 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
14e80 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
14e90 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
14ea0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
14eb0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
14ec0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
14ed0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
14ee0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
14ef0 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
14f00 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
14f10 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
14f20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
14f30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
14f40 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  code()] or [sqli
14f50 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
14f60 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
14f70 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31 7d 20  .**.** {H12371} 
14f80 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 67 65  If a [sqlite3_ge
14f90 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 6c 73  t_table()] fails
14fa0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
14fb0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  tion, then.**   
14fc0 20 20 20 20 20 20 20 69 74 20 73 68 61 6c 6c 20         it shall 
14fd0 66 72 65 65 20 74 68 65 20 72 65 73 75 6c 74 20  free the result 
14fe0 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73  table under cons
14ff0 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 20  truction, abort 
15000 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
15010 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73  query in process
15020 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 62 73 65  , skip any subse
15030 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73  quent queries, s
15040 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
15050 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 20 6f 75     *pazResult ou
15060 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20  tput pointer to 
15070 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 20  NULL and return 
15080 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
15090 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d 20 49  **.** {H12373} I
150a0 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e 20 70  f the pnColumn p
150b0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
150c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
150d0 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a  ] is not NULL.**
150e0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 61            then a
150f0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
15100 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
15110 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
15120 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  shall.**        
15130 20 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d 62    write the numb
15140 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
15150 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
15160 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
15170 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70  he query into *p
15180 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  nColumn..**.** {
15190 48 31 32 33 37 34 7d 20 49 66 20 74 68 65 20 70  H12374} If the p
151a0 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74  nRow parameter t
151b0 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  o [sqlite3_get_t
151c0 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e  able()] is not N
151d0 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ULL.**          
151e0 74 68 65 6e 20 61 20 73 75 63 63 65 73 73 66 75  then a successfu
151f0 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
15200 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
15210 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20  le()] shall.**  
15220 20 20 20 20 20 20 20 20 77 72 69 74 65 73 20 74          writes t
15230 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
15240 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  s in the.**     
15250 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20       result set 
15260 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 74  of the query int
15270 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20  o *pnRow..**.** 
15280 7b 48 31 32 33 37 36 7d 20 41 20 73 75 63 63 65  {H12376} A succe
15290 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
152a0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   of [sqlite3_get
152b0 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 74 20 63  _table()] that c
152c0 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20 20 20  omputes.**      
152d0 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 20 72 65      N rows of re
152e0 73 75 6c 74 20 77 69 74 68 20 43 20 63 6f 6c 75  sult with C colu
152f0 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 68 61 6c  mns per row shal
15300 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73 75 6c  l make *pazResul
15310 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  t.**          po
15320 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 61 79 20  int to an array 
15330 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 28  of pointers to (
15340 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 73 20 77  N+1)*C strings w
15350 68 65 72 65 20 74 68 65 20 66 69 72 73 74 0a 2a  here the first.*
15360 2a 20 20 20 20 20 20 20 20 20 20 43 20 73 74 72  *          C str
15370 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d 6e 20  ings are column 
15380 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 69 6e 65  names as obtaine
15390 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  d from.**       
153a0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
153b0 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 74  mn_name()] and t
153c0 68 65 20 72 65 73 74 20 61 72 65 20 63 6f 6c 75  he rest are colu
153d0 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c 75 65 73  mn result values
153e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74  .**          obt
153f0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
15400 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
15410 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37  )]..**.** {H1237
15420 39 7d 20 54 68 65 20 76 61 6c 75 65 73 20 69 6e  9} The values in
15430 20 74 68 65 20 70 61 7a 52 65 73 75 6c 74 20 61   the pazResult a
15440 72 72 61 79 20 72 65 74 75 72 6e 65 64 20 62 79  rray returned by
15450 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
15460 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ble()].**       
15470 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69 6e 20     shall remain 
15480 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c 65 61  valid until clea
15490 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  red by [sqlite3_
154a0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
154b0 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20 57 68  *.** {H12382} Wh
154c0 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
154d0 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61  rs during evalua
154e0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
154f0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a  _get_table()].**
15500 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66 75            the fu
15510 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74  nction shall set
15520 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f 20 4e   *pazResult to N
15530 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20 65 72  ULL, write an er
15540 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
15550 20 20 20 20 20 20 20 20 69 6e 74 6f 20 6d 65 6d          into mem
15560 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
15570 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
15580 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 20 20  c()], make.**   
15590 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 72 6d 73         **pzErrms
155a0 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20  g point to that 
155b0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c 20 61  error message, a
155c0 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 20  nd return a.**  
155d0 20 20 20 20 20 20 20 20 61 70 70 72 6f 70 72 69          appropri
155e0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
155f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
15600 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
15610 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
15620 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
15630 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
15640 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
15650 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
15660 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
15670 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
15680 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
15690 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
156a0 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
156b0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
156c0 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
156d0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
156e0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
156f0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
15700 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
15710 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
15720 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
15730 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
15740 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
15750 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
15760 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
15770 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
15780 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
15790 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
157a0 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
157b0 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30  Functions {H1740
157c0 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30  0} <S70000><S200
157d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
157e0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
157f0 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  kalikes of the "
15800 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
15810 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
15820 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
15830 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
15840 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
15850 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
15860 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
15870 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
15880 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
15890 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
158a0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
158b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
158c0 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
158d0 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
158e0 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
158f0 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
15900 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
15910 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f  ree()].  Both ro
15920 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
15930 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
15940 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
15950 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
15960 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
15970 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
15980 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
15990 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
159a0 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   In sqlite3_snpr
159b0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
159c0 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
159d0 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
159e0 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
159f0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
15a00 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
15a10 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
15a20 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
15a30 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
15a40 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
15a50 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
15a60 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
15a70 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
15a80 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
15a90 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
15aa0 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
15ab0 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
15ac0 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  ().  This is an.
15ad0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
15ae0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
15af0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
15b00 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
15b10 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
15b20 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61  ibility.  Note a
15b30 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
15b40 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
15b50 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
15b60 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
15b70 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
15b80 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
15b90 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
15ba0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
15bb0 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69  buffer.  We admi
15bc0 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
15bd0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
15be0 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
15bf0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
15c00 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
15c10 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
15c20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
15c30 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
15c40 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
15c50 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
15c60 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
15c70 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  ility..**.** As 
15c80 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
15c90 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
15ca0 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
15cb0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
15cc0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
15cd0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
15ce0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
15cf0 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66  rminated.  The f
15d00 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
15d10 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
15d20 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
15d30 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
15d40 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
15d50 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
15d60 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
15d70 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
15d80 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
15d90 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
15da0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
15db0 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  rs..**.** These 
15dc0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
15dd0 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
15de0 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
15df0 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
15e00 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
15e10 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
15e20 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
15e30 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
15e40 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
15e50 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
15e60 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
15e70 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
15e80 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
15e90 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
15ea0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70  .**.** The %q op
15eb0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
15ec0 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
15ed0 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
15ee0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
15ef0 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
15f00 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
15f10 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
15f20 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
15f30 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
15f40 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
15f50 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
15f60 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20  ng literal.  By 
15f70 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c  doubling each '\
15f80 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20  ''.** character 
15f90 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20  it escapes that 
15fa0 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c  character and al
15fb0 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e  lows it to be in
15fc0 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  serted into.** t
15fd0 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  he string..**.**
15fe0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73   For example, as
15ff0 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20  sume the string 
16000 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63  variable zText c
16010 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20  ontains text as 
16020 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
16030 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
16040 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74  .**  char *zText
16050 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79   = "It's a happy
16060 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65   day!";.** </pre
16070 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
16080 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65  *.** One can use
16090 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e   this text in an
160a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
160b0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
160c0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
160d0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
160e0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
160f0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
16100 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25   table VALUES('%
16110 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  q')", zText);.**
16120 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
16130 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
16140 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
16150 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
16160 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
16170 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  >.**.** Because 
16180 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74  the %q format st
16190 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ring is used, th
161a0 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  e '\'' character
161b0 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20   in zText.** is 
161c0 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20  escaped and the 
161d0 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73  SQL generated is
161e0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
161f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
16200 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
16210 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
16220 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70  ES('It''s a happ
16230 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72  y day!').** </pr
16240 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
16250 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f  **.** This is co
16260 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75  rrect.  Had we u
16270 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f  sed %s instead o
16280 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61  f %q, the genera
16290 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64  ted SQL.** would
162a0 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b   have looked lik
162b0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e this:.**.** <b
162c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
162d0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
162e0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
162f0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
16300 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  ');.** </pre></b
16310 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
16320 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61   This second exa
16330 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73  mple is an SQL s
16340 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73  yntax error.  As
16350 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20   a general rule 
16360 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c  you should.** al
16370 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74  ways use %q inst
16380 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69  ead of %s when i
16390 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e  nserting text in
163a0 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  to a string lite
163b0 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25  ral..**.** The %
163c0 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
163d0 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
163e0 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
163f0 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
16400 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
16410 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
16420 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
16430 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
16440 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
16450 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
16460 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
16470 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
16480 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
16490 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
164a0 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63   quotes) in plac
164b0 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69  e of the %Q opti
164c0 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  on.  So, for exa
164d0 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
164e0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
164f0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
16500 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
16510 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
16520 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
16530 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
16540 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
16550 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
16560 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
16570 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
16580 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
16590 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
165a0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
165b0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
165c0 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
165d0 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
165e0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
165f0 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
16600 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
16610 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
16620 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
16630 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
16640 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73  exactly like "%s
16650 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  " with the.** ad
16660 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
16670 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
16680 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
16690 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
166a0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
166b0 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
166c0 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
166d0 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a  t string. {END}.
166e0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
166f0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 33 7d  :.**.** {H17403}
16700 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
16710 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73  printf()] and [s
16720 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
16730 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
16740 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
16750 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72  n either pointer
16760 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
16770 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
16780 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20  gs held in.**   
16790 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f          memory o
167a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
167b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
167c0 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  or NULL pointers
167d0 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
167e0 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
167f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61  te3_malloc()] fa
16800 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34  ils..**.** {H174
16810 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  06}  The [sqlite
16820 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e  3_snprintf()] in
16830 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20 61  terface writes a
16840 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
16850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55 54  .**           UT
16860 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20  F-8 string into 
16870 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74  the buffer point
16880 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ed to by the sec
16890 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
168a0 20 20 20 20 20 20 20 20 20 20 20 70 72 6f 76 69             provi
168b0 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69 72  ded that the fir
168c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
168d0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
168e0 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 37  o..**.** {H17407
168f0 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
16900 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  snprintf()] inte
16910 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77  rface does not w
16920 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a  rite slots of.**
16930 20 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6f             its o
16940 75 74 70 75 74 20 62 75 66 66 65 72 20 28 74 68  utput buffer (th
16950 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16960 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 65 20  er) outside the 
16970 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  range.**        
16980 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20     of 0 through 
16990 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73 20  N-1 (where N is 
169a0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
169b0 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  ter).**         
169c0 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20    regardless of 
169d0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
169e0 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  e string.**     
169f0 20 20 20 20 20 20 72 65 71 75 65 73 74 65 64 20        requested 
16a00 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70  by the format sp
16a10 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a  ecification..*/.
16a20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
16a30 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
16a40 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
16a50 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
16a60 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
16a70 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
16a80 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
16a90 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
16aa0 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  r*, ...);../*.**
16ab0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
16ac0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
16ad0 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30 7d 20  system {H17300} 
16ae0 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20000>.**.** T
16af0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20  he SQLite core  
16b00 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
16b10 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
16b20 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
16b30 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
16b40 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
16b50 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
16b60 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
16b70 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
16b80 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
16b90 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
16ba0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
16bb0 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
16bc0 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
16bd0 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
16be0 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
16bf0 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
16c00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
16c10 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
16c20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
16c30 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
16c40 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
16c50 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
16c60 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
16c70 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
16c80 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  ** If sqlite3_ma
16c90 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
16ca0 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
16cb0 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
16cc0 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
16cd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
16ce0 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74    If the paramet
16cf0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
16d00 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
16d10 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
16d20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
16d30 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
16d40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
16d50 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73  .**.** Calling s
16d60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
16d70 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
16d80 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
16d90 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
16da0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
16db0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
16dc0 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
16dd0 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
16de0 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
16df0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72    The sqlite3_fr
16e00 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
16e10 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
16e20 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
16e30 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
16e40 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
16e50 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
16e60 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
16e70 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
16e80 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
16e90 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
16ea0 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
16eb0 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
16ec0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
16ed0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
16ee0 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
16ef0 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
16f00 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
16f10 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
16f20 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
16f30 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
16f40 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
16f50 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
16f60 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
16f70 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
16f80 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
16f90 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
16fa0 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
16fb0 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
16fc0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
16fd0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
16fe0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  alloc()..**.** T
16ff0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
17000 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
17010 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
17020 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
17030 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
17040 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
17050 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
17060 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
17070 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
17080 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
17090 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
170a0 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
170b0 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74  parameter.  If t
170c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
170d0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
170e0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
170f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
17100 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
17110 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
17120 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
17130 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
17140 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
17150 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
17160 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17170 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f  ..** If the seco
17180 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
17190 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
171a0 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
171b0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
171c0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
171d0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
171e0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
171f0 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
17200 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
17210 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
17220 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17230 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  ..** sqlite3_rea
17240 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
17250 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
17260 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
17270 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
17280 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
17290 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
172a0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
172b0 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49  navailable..** I
172c0 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
172d0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
172e0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
172f0 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
17300 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
17310 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
17320 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
17330 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
17340 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
17350 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17360 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
17370 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
17380 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  ed..** If sqlite
17390 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
173a0 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
173b0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
173c0 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
173d0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  eed..**.** The m
173e0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
173f0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
17400 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
17410 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
17420 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
17430 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
17440 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45  yte boundary. {E
17450 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  ND}.**.** The de
17460 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61  fault implementa
17470 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f  tion of the memo
17480 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
17490 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20  bsystem uses.** 
174a0 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  the malloc(), re
174b0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
174c0 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  () provided by t
174d0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
174e0 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38  brary..** {H1738
174f0 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53  2} However, if S
17500 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
17510 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
17520 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45  LITE_MEMORY_SIZE
17530 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72  =<i>NNN</i> C pr
17540 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
17550 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f   (where <i>NNN</
17560 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65  i>.** is an inte
17570 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74  ger), then SQLit
17580 65 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69  e create a stati
17590 63 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65  c array of at le
175a0 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69  ast.** <i>NNN</i
175b0 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  > bytes in size 
175c0 61 6e 64 20 75 73 65 73 20 74 68 61 74 20 61 72  and uses that ar
175d0 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  ray for all of i
175e0 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65  ts dynamic.** me
175f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
17600 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64  needs. {END}  Ad
17610 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20  ditional memory 
17620 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e  allocator option
17630 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65  s.** may be adde
17640 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
17650 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  ases..**.** In S
17660 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
17670 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
17680 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
17690 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
176a0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
176b0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
176c0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
176d0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
176e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
176f0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
17700 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
17710 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
17720 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
17730 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
17740 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
17750 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
17760 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  be used..**.** T
17770 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
17780 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
17790 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  lls.** the syste
177a0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
177b0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
177c0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
177d0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
177e0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
177f0 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
17800 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
17810 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
17820 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
17830 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
17840 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
17850 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
17860 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
17870 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65  rors are detecte
17880 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61  d, but.** they a
17890 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
178a0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
178b0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
178c0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
178d0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
178e0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  OMEM]..**.** INV
178f0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
17900 48 31 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71  H17303}  The [sq
17910 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
17920 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
17930 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e  ns either a poin
17940 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
17950 20 20 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63      a newly chec
17960 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66  ked-out block of
17970 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
17980 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  s of memory.**  
17990 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73           that is
179a0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c   8-byte aligned,
179b0 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e   or it returns N
179c0 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61  ULL if it is una
179d0 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
179e0 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20   to fulfill the 
179f0 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b  request..**.** {
17a00 48 31 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71  H17304}  The [sq
17a10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
17a20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
17a30 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
17a40 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r if.**         
17a50 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e    N is less than
17a60 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
17a70 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 35  o..**.** {H17305
17a80 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
17a90 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61  free(P)] interfa
17aa0 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f  ce releases memo
17ab0 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  ry previously.**
17ac0 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
17ad0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
17ae0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
17af0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17b00 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
17b10 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c   making it avail
17b20 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a  able for reuse..
17b30 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 36 7d 20 20  **.** {H17306}  
17b40 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
17b50 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69  e3_free(NULL)] i
17b60 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
17b70 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31  op..**.** {H1731
17b80 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  0}  A call to [s
17b90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30  qlite3_realloc(0
17ba0 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65  ,N)] is equivale
17bb0 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20  nt to a call.** 
17bc0 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71            to [sq
17bd0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
17be0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 32 7d  ..**.** {H17312}
17bf0 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
17c00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30  ite3_realloc(P,0
17c10 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  )] is equivalent
17c20 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20   to a call.**   
17c30 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69          to [sqli
17c40 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a  te3_free(P)]..**
17c50 0a 2a 2a 20 7b 48 31 37 33 31 35 7d 20 20 54 68  .** {H17315}  Th
17c60 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
17c70 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  es [sqlite3_mall
17c80 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
17c90 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20  realloc()],.**  
17ca0 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71           and [sq
17cb0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f  lite3_free()] fo
17cc0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d  r all of its mem
17cd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ory allocation a
17ce0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  nd.**           
17cf0 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  deallocation nee
17d00 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31  ds..**.** {H1731
17d10 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  8}  The [sqlite3
17d20 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69  _realloc(P,N)] i
17d30 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
17d40 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65   either a pointe
17d50 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  r.**           t
17d60 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65  o a block of che
17d70 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20  cked-out memory 
17d80 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
17d90 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20  tes in size.**  
17da0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73           that is
17db0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c   8-byte aligned,
17dc0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
17dd0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32  er..**.** {H1732
17de0 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  1}  When [sqlite
17df0 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20  3_realloc(P,N)] 
17e00 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55  returns a non-NU
17e10 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66  LL pointer, it f
17e20 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  irst.**         
17e30 20 20 63 6f 70 69 65 73 20 74 68 65 20 66 69 72    copies the fir
17e40 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f  st K bytes of co
17e50 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74  ntent from P int
17e60 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20  o the newly.**  
17e70 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74           allocat
17e80 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20  ed block, where 
17e90 4b 20 69 73 20 74 68 65 20 6c 65 73 73 65 72 20  K is the lesser 
17ea0 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a  of N and the siz
17eb0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
17ec0 20 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a    the buffer P..
17ed0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 32 7d 20 20  **.** {H17322}  
17ee0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  When [sqlite3_re
17ef0 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75  alloc(P,N)] retu
17f00 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  rns a non-NULL p
17f10 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74  ointer, it first
17f20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
17f30 6c 65 61 73 65 73 20 74 68 65 20 62 75 66 66 65  leases the buffe
17f40 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  r P..**.** {H173
17f50 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74  23}  When [sqlit
17f60 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
17f70 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
17f80 68 65 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a  he buffer P is.*
17f90 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20  *           not 
17fa0 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65  modified or rele
17fb0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  ased..**.** ASSU
17fc0 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
17fd0 41 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69  A17350}  The poi
17fe0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
17ff0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
18000 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
18010 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20  realloc()].**   
18020 20 20 20 20 20 20 20 20 6d 75 73 74 20 62 65 20          must be 
18030 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
18040 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
18050 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
18060 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
18070 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
18080 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18090 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
180a0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
180b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e  e.**           n
180c0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
180d0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37  ased..**.** {A17
180e0 33 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63  351}  The applic
180f0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
18100 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
18110 20 70 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20   part of.**     
18120 20 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66        a block of
18130 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
18140 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
18150 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
18160 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66        [sqlite3_f
18170 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
18180 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
18190 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
181a0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
181b0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
181c0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
181d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
181e0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
181f0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
18200 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
18210 69 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20  istics {H17370} 
18220 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53  <S30210>.**.** S
18230 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
18240 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
18250 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
18260 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
18270 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
18280 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
18290 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
182a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
182b0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
182c0 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
182d0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
182e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
182f0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
18300 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
18310 2a 20 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b  * {H17371} The [
18320 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
18330 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
18340 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
18350 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20  r of bytes.**   
18360 20 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79         of memory
18370 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
18380 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
18390 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
183a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20  .**.** {H17373} 
183b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
183c0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
183d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
183e0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
183f0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
18400 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
18410 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
18420 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
18430 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ark.**          
18440 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a  was last reset..
18450 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54  **.** {H17374} T
18460 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
18470 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
18480 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
18490 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
184a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
184b0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
184c0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
184d0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65  **          adde
184e0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
184f0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
18500 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
18510 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  lloc()],.**     
18520 20 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65       but not ove
18530 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
18540 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
18550 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
18560 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75  .**          rou
18570 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
18580 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
18590 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  y call..**.** {H
185a0 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72  17375} The memor
185b0 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
185c0 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
185d0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
185e0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  of.**          [
185f0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
18600 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
18610 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
18620 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
18630 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f     [sqlite3_memo
18640 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
18650 69 73 20 74 72 75 65 2e 20 20 54 68 65 20 76 61  is true.  The va
18660 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
18670 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c           by [sql
18680 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
18690 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
186a0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
186b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69  .**          pri
186c0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
186d0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
186e0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
186f0 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
18700 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
18710 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
18720 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
18730 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
18740 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
18750 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
18760 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32  tor {H17390} <S2
18770 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  0000>.**.** SQLi
18780 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
18790 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
187a0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
187b0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
187c0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
187d0 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
187e0 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
187f0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
18800 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
18810 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
18820 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
18830 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
18840 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
18850 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
18860 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
18870 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
18880 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
18890 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
188a0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
188b0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
188c0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
188d0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
188e0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
188f0 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  ** A call to thi
18900 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
18910 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
18920 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
18930 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er P..**.** The 
18940 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
18950 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
18960 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
18970 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
18980 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
18990 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
189a0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
189b0 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
189c0 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
189d0 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
189e0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
189f0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
18a00 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65  .** On all subse
18a10 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
18a20 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
18a30 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
18a40 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
18a50 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
18a60 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
18a70 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
18a80 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
18a90 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  hod..**.** INVAR
18aa0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
18ab0 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  7392} The [sqlit
18ac0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c  e3_randomness(N,
18ad0 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72  P)] interface wr
18ae0 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a  ites N bytes of.
18af0 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69 67 68  **          high
18b00 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
18b10 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
18b20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69  buffer P..*/.voi
18b30 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
18b40 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
18b50 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
18b60 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
18b70 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
18b80 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32  n Callbacks {H12
18b90 35 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a  500} <S70100>.**
18ba0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
18bb0 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74   registers a aut
18bc0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18bd0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
18be0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
18bf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
18c00 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
18c10 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
18c20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
18c30 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
18c40 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
18c50 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
18c60 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
18c70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
18c80 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
18c90 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
18ca0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
18cb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
18cc0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
18cd0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
18ce0 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20    At various.** 
18cf0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
18d00 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
18d10 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
18d20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
18d30 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
18d40 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
18d50 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18d60 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
18d70 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
18d80 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
18d90 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20  e allowed.  The 
18da0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18db0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
18dc0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
18dd0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
18de0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
18df0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
18e00 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
18e10 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
18e20 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
18e30 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
18e40 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
18e50 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
18e60 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
18e70 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
18e80 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
18e90 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
18ea0 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20   error.  If the 
18eb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18ec0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
18ed0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
18ee0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
18ef0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
18f00 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
18f10 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
18f20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18f30 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
18f40 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
18f50 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
18f60 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
18f70 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
18f80 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
18f90 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
18fa0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
18fb0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
18fc0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
18fd0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
18fe0 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63   ok.  When the c
18ff0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
19000 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
19010 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
19020 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
19030 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
19040 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
19050 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
19060 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
19070 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
19080 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
19090 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
190a0 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20 61 75  nied.  If the au
190b0 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73  thorizer code is
190c0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
190d0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
190e0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
190f0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
19100 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
19110 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
19120 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
19130 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
19140 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
19150 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
19160 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
19170 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
19180 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
19190 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
191a0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
191b0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
191c0 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
191d0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
191e0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
191f0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
19200 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
19210 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
19220 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
19230 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
19240 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19250 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
19260 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
19270 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
19280 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
19290 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
192a0 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  ce. The second p
192b0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
192c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
192d0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
192e0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
192f0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
19300 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
19310 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
19320 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
19330 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
19340 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
19350 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
19360 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
19370 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
19380 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
19390 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
193a0 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
193b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
193c0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e  orized..**.** An
193d0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
193e0 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
193f0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
19400 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
19410 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
19420 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
19430 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
19440 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
19450 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
19460 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
19470 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
19480 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
19490 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
194a0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
194b0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
194c0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
194d0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
194e0 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
194f0 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
19500 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
19510 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
19520 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
19530 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
19540 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
19550 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
19560 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
19570 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
19580 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
19590 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
195a0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
195b0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
195c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
195d0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
195e0 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
195f0 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
19600 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
19610 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
19620 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
19630 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
19640 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
19650 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
19660 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
19670 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
19680 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
19690 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
196a0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
196b0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
196c0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
196d0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
196e0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
196f0 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
19700 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
19710 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
19720 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
19730 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
19740 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
19750 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  orizer..**.** On
19760 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
19770 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
19780 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
19790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
197a0 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
197b0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
197c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
197d0 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
197e0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
197f0 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65 20  l.  Disable the 
19800 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
19810 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
19820 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
19830 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
19840 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
19850 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
19860 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
19870 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
19880 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
19890 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
198a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
198b0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
198c0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
198d0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
198e0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
198f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
19900 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19910 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
19920 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
19930 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
19940 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
19950 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
19960 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
19970 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   When [sqlite3_p
19980 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
19990 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
199a0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
199b0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
199c0 67 68 74 20 62 65 20 72 65 70 72 65 70 61 72 65  ght be reprepare
199d0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
199e0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
199f0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
19a00 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
19a10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
19a20 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
19a30 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
19a40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19a50 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
19a60 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
19a70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19a80 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
19a90 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
19aa0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
19ab0 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
19ac0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
19ad0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
19ae0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
19af0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
19b00 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
19b10 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
19b20 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
19b30 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
19b40 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
19b50 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20 54 68  *.** {H12501} Th
19b60 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
19b70 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29  uthorizer(D,...)
19b80 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
19b90 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20  sters a.**      
19ba0 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63      authorizer c
19bb0 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74  allback with dat
19bc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19bd0 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30   D..**.** {H1250
19be0 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  2} The authorize
19bf0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
19c00 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
19c10 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20  tements are.**  
19c20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 70 61          being pa
19c30 72 73 65 65 64 20 61 6e 64 20 63 6f 6d 70 69 6c  rseed and compil
19c40 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30  ed..**.** {H1250
19c50 33 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  3} If the author
19c60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
19c70 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20  turns any value 
19c80 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20  other than.**   
19c90 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
19ca0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
19cb0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
19cc0 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20  DENY], then.**  
19cd0 20 20 20 20 20 20 20 20 74 68 65 20 61 70 70 6c          the appl
19ce0 69 63 61 74 69 6f 6e 20 69 6e 74 65 72 66 61 63  ication interfac
19cf0 65 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73  e call that caus
19d00 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
19d10 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19d20 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68  llback to run sh
19d30 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  all fail with an
19d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
19d50 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f  LITE_ERROR] erro
19d60 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70  r code and an ap
19d70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
19d80 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b  message..**.** {
19d90 48 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65  H12504} When the
19da0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19db0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
19dc0 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70  LITE_OK], the op
19dd0 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  eration.**      
19de0 20 20 20 20 64 65 73 63 72 69 62 65 64 20 69 73      described is
19df0 20 70 72 6f 63 65 73 73 65 64 20 6e 6f 72 6d 61   processed norma
19e00 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  lly..**.** {H125
19e10 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74  05} When the aut
19e20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19e30 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
19e40 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20  _DENY], the.**  
19e50 20 20 20 20 20 20 20 20 61 70 70 6c 69 63 61 74          applicat
19e60 69 6f 6e 20 69 6e 74 65 72 66 61 63 65 20 63 61  ion interface ca
19e70 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 20 74  ll that caused t
19e80 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  he.**          a
19e90 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19ea0 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20  ck to run shall 
19eb0 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  fail.**         
19ec0 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45   with an [SQLITE
19ed0 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f  _ERROR] error co
19ee0 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20  de and an error 
19ef0 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20  message.**      
19f00 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74      explaining t
19f10 68 61 74 20 61 63 63 65 73 73 20 69 73 20 64 65  hat access is de
19f20 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  nied..**.** {H12
19f30 35 30 36 7d 20 49 66 20 74 68 65 20 61 75 74 68  506} If the auth
19f40 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65  orizer code (the
19f50 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
19f60 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
19f70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
19f80 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54  lback) is [SQLIT
19f90 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20  E_READ] and the 
19fa0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19fb0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ack returns.**  
19fc0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
19fd0 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68  IGNORE], then th
19fe0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
19ff0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
1a000 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ted to.**       
1a010 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c     insert a NULL
1a020 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
1a030 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
1a040 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
1a050 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ave.**          
1a060 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
1a070 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
1a080 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  n returned..**.*
1a090 2a 20 7b 48 31 32 35 30 37 7d 20 49 66 20 74 68  * {H12507} If th
1a0a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  e authorizer cod
1a0b0 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d  e (the 2nd param
1a0c0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1a0d0 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20  orizer.**       
1a0e0 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20     callback) is 
1a0f0 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74  anything other t
1a100 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  han [SQLITE_READ
1a110 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  ], then.**      
1a120 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20      a return of 
1a130 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1a140 68 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66  has the same eff
1a150 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44  ect as [SQLITE_D
1a160 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ENY]..**.** {H12
1a170 35 31 30 7d 20 54 68 65 20 66 69 72 73 74 20 70  510} The first p
1a180 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1a190 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1a1a0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
1a1b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1a1c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
1a1d0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1a1e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1a1f0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
1a200 0a 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54 68 65  .** {H12511} The
1a210 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a220 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
1a230 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  k is an integer.
1a240 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
1a250 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
1a260 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
1a270 63 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69  cifies the parti
1a280 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20  cular action.** 
1a290 20 20 20 20 20 20 20 20 20 74 6f 20 62 65 20 61           to be a
1a2a0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1a2b0 20 7b 48 31 32 35 31 32 7d 20 54 68 65 20 74 68   {H12512} The th
1a2c0 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
1a2d0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1a2e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
1a2f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
1a300 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1a310 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
1a320 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64  n.**          ad
1a330 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
1a340 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
1a350 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1a360 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32  ed..**.** {H1252
1a370 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  0} Each call to 
1a380 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1a390 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72  horizer()] overr
1a3a0 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ides.**         
1a3b0 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
1a3c0 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72  installed author
1a3d0 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  izer..**.** {H12
1a3e0 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68  521} A NULL auth
1a3f0 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61  orizer means tha
1a400 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69  t no authorizati
1a410 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  on.**          c
1a420 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1a430 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32  ed..**.** {H1252
1a440 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 61  2} The default a
1a450 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c  uthorizer is NUL
1a460 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
1a470 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1a480 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1a490 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1a4a0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1a4b0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1a4c0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1a4d0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1a4e0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1a4f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1a500 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1a510 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20   Codes {H12590} 
1a520 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12500>.**.** T
1a530 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1a540 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1a550 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1a560 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
1a570 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
1a580 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
1a590 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
1a5a0 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
1a5b0 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
1a5c0 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
1a5d0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
1a5e0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
1a5f0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
1a600 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1a610 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1a620 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
1a630 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1a640 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1a650 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a660 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
1a670 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
1a680 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
1a690 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
1a6a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
1a6b0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
1a6c0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
1a6d0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
1a6e0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
1a6f0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1a700 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
1a710 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30   {H12550} <H1250
1a720 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0>.**.** The [sq
1a730 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1a740 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1a750 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1a760 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1a770 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1a780 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1a790 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1a7a0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1a7b0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1a7c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1a7d0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1a7e0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1a7f0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1a800 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1a810 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1a820 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1a830 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1a840 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1a850 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1a860 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1a870 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1a880 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1a890 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1a8a0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1a8b0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1a8c0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1a8d0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1a8e0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1a8f0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1a900 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1a910 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1a920 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1a930 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1a940 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1a950 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1a960 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
1a970 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1a980 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
1a990 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1a9a0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1a9b0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
1a9c0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
1a9d0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1a9e0 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72  le.  The 6th par
1a9f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1aa00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1aa10 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1aa20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1aa30 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1aa40 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1aa50 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1aa60 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1aa70 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1aa80 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1aa90 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1aaa0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1aab0 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e  L code..**.** IN
1aac0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1aad0 7b 48 31 32 35 35 31 7d 20 54 68 65 20 73 65 63  {H12551} The sec
1aae0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1aaf0 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
1ab00 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1ab10 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1ab20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73  izer callback] s
1ab30 68 61 6c 6c 20 62 65 20 61 6e 20 69 6e 74 65 67  hall be an integ
1ab40 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  er.**          [
1ab50 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75  SQLITE_COPY | au
1ab60 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 74  thorizer code] t
1ab70 68 61 74 20 73 70 65 63 69 66 69 65 73 20 77 68  hat specifies wh
1ab80 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  at action.**    
1ab90 20 20 20 20 20 20 69 73 20 62 65 69 6e 67 20 61        is being a
1aba0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
1abb0 20 7b 48 31 32 35 35 32 7d 20 54 68 65 20 33 72   {H12552} The 3r
1abc0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1abd0 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 20  ters to the.**  
1abe0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1abf0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1ac00 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  | authorization 
1ac10 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20 20  callback].**    
1ac20 20 20 20 20 20 20 73 68 61 6c 6c 20 62 65 20 70        shall be p
1ac30 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
1ac40 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
1ac50 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  hich.**         
1ac60 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1ac70 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d  authorizer code]
1ac80 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
1ac90 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1aca0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 33 7d  ..**.** {H12553}
1acb0 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
1acc0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  er to the.**    
1acd0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
1ace0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1acf0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1ad00 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 74 68  ack] shall be th
1ad10 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e name.**       
1ad20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61     of the databa
1ad30 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61  se (example: "ma
1ad40 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63  in", "temp", etc
1ad50 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1ad60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 34 7d  ..**.** {H12554}
1ad70 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74   The 6th paramet
1ad80 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  er to the.**    
1ad90 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
1ada0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1adb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1adc0 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 74 68  ack] shall be th
1add0 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e name.**       
1ade0 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d     of the inner-
1adf0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1ae00 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1ae10 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1ae20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 63 63           the acc
1ae30 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
1ae40 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
1ae50 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
1ae60 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 20  rectly from.**  
1ae70 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65 76 65          top-leve
1ae80 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1ae90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aea0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aeb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1aec0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1aed0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1aee0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1aef0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1af00 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1af10 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1af20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1af30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1af40 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1af50 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1af60 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1af70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1af80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1af90 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1afa0 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1afb0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1afc0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1afd0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1afe0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1aff0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1b000 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1b010 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b020 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1b030 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1b040 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1b050 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1b060 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b070 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1b080 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1b090 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1b0a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b0b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b0c0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1b0d0 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1b0e0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1b0f0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1b100 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b110 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1b120 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1b130 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1b140 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b150 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b160 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1b170 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1b180 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1b190 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b1a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b1b0 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
1b1c0 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
1b1d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1b1e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b1f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b200 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
1b210 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
1b220 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b230 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b240 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b250 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
1b260 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
1b270 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1b280 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1b290 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b2a0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
1b2b0 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
1b2c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1b2d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b2e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b2f0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
1b300 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
1b310 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1b320 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1b330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b340 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
1b350 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
1b360 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1b370 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b380 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1b390 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
1b3a0 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
1b3b0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1b3c0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1b3d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1b3e0 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
1b3f0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
1b400 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1b410 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b420 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
1b430 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
1b440 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
1b450 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1b460 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b470 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
1b480 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
1b490 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
1b4a0 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
1b4b0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
1b4c0 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
1b4d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1b4e0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1b4f0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1b500 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1b510 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
1b520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
1b530 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1b540 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b550 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b560 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
1b570 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
1b580 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1b590 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b5a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b5b0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
1b5c0 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
1b5d0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b5e0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1b5f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b600 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
1b610 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
1b620 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
1b630 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b640 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b650 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
1b660 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
1b670 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1b680 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b690 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b6a0 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
1b6b0 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
1b6c0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1b6d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b6e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b6f0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
1b700 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
1b710 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1b720 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b740 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
1b750 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
1b760 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1b770 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b780 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b790 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
1b7a0 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
1b7b0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1b7c0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1b7d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b7e0 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
1b7f0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
1b800 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1b810 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1b820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1b830 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
1b840 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
1b850 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
1b860 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
1b870 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
1b880 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
1b890 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
1b8a0 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
1b8b0 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
1b8c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
1b8d0 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
1b8e0 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
1b8f0 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
1b900 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1b910 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1b920 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31  ng Functions {H1
1b930 32 32 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2280} <S60400>.*
1b940 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
1b950 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1b960 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
1b970 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
1b980 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
1b990 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
1b9a0 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
1b9b0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
1b9c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1b9d0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
1b9e0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1b9f0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1ba00 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
1ba10 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
1ba20 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
1ba30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
1ba40 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
1ba50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1ba60 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
1ba70 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20  returns a UTF-8 
1ba80 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
1ba90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1baa0 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74  ext.** as the st
1bab0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
1bac0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20  gins executing. 
1bad0 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c   Additional call
1bae0 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61  backs occur.** a
1baf0 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
1bb00 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
1bb10 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
1bb20 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
1bb30 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
1bb40 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
1bb50 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
1bb60 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a  es the trigger..
1bb70 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
1bb80 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1bb90 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1bba0 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
1bbb0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
1bbc0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
1bbd0 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70  finishes.  The p
1bbe0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
1bbf0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
1bc00 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
1bc10 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
1bc20 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
1bc30 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
1bc40 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
1bc50 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
1bc60 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   run..**.** INVA
1bc70 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
1bc80 31 32 32 38 31 7d 20 54 68 65 20 63 61 6c 6c 62  12281} The callb
1bc90 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1bca0 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
1bcb0 74 65 33 5f 74 72 61 63 65 28 29 5d 20 0a 2a 2a  te3_trace()] .**
1bcc0 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
1bcd0 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20  be invoked.**   
1bce0 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20         whenever 
1bcf0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1bd00 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f   first begins to
1bd10 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20   execute and.** 
1bd20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65           wheneve
1bd30 72 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70  r a trigger subp
1bd40 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65 67  rogram first beg
1bd50 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a  ins to run..**.*
1bd60 2a 20 7b 48 31 32 32 38 32 7d 20 45 61 63 68 20  * {H12282} Each 
1bd70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1bd80 5f 74 72 61 63 65 28 29 5d 20 73 68 61 6c 6c 20  _trace()] shall 
1bd90 6f 76 65 72 72 69 64 65 20 74 68 65 20 70 72 65  override the pre
1bda0 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20  viously.**      
1bdb0 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74      registered t
1bdc0 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  race callback..*
1bdd0 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d 20 41 20  *.** {H12283} A 
1bde0 4e 55 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c 62  NULL trace callb
1bdf0 61 63 6b 20 73 68 61 6c 6c 20 64 69 73 61 62 6c  ack shall disabl
1be00 65 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e tracing..**.**
1be10 20 7b 48 31 32 32 38 34 7d 20 54 68 65 20 66 69   {H12284} The fi
1be20 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1be30 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61  the trace callba
1be40 63 6b 20 73 68 61 6c 6c 20 62 65 20 61 20 63 6f  ck shall be a co
1be50 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  py of.**        
1be60 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68    the pointer wh
1be70 69 63 68 20 77 61 73 20 74 68 65 20 33 72 64 20  ich was the 3rd 
1be80 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
1be90 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a  ite3_trace()]..*
1bea0 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54 68  *.** {H12285} Th
1beb0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1bec0 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
1bed0 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20  allback is a.** 
1bee0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1bef0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1bf00 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
1bf10 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65   the original te
1bf20 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  xt.**          o
1bf30 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
1bf40 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 61  ent as it was pa
1bf50 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74  ssed into [sqlit
1bf60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1bf70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1bf80 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20  the equivalent, 
1bf90 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e  or an SQL commen
1bfa0 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  t indicating the
1bfb0 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20   beginning.**   
1bfc0 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 69 67         of a trig
1bfd0 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a  ger subprogram..
1bfe0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20 54  **.** {H12287} T
1bff0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1c000 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1c010 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66  by [sqlite3_prof
1c020 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ile()] is invoke
1c030 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  d.**          as
1c040 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
1c050 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a  ent finishes..**
1c060 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20 54 68 65  .** {H12288} The
1c070 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1c080 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
1c090 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
1c0a0 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  py of.**        
1c0b0 20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65    the 3rd parame
1c0c0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1c0d0 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  profile()]..**.*
1c0e0 2a 20 7b 48 31 32 32 38 39 7d 20 54 68 65 20 73  * {H12289} The s
1c0f0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1c100 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63  to the profile c
1c110 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20  allback is a.** 
1c120 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
1c130 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1c140 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61  tring that conta
1c150 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65  ins the complete
1c160 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20   text of.**     
1c170 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 74 61       the SQL sta
1c180 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73  tement as it was
1c190 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73   processed by [s
1c1a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1c1b0 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  2()].**         
1c1c0 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
1c1d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39  nt..**.** {H1229
1c1e0 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 61 72  0} The third par
1c1f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72  ameter to the pr
1c200 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69  ofile callback i
1c210 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a  s an estimate.**
1c220 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
1c230 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73   number of nanos
1c240 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63  econds of wall-c
1c250 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72  lock time requir
1c260 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ed to.**        
1c270 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74    run the SQL st
1c280 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61  atement from sta
1c290 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f  rt to finish..*/
1c2a0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
1c2b0 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
1c2c0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
1c2d0 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
1c2e0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1c2f0 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
1c300 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
1c310 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
1c320 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
1c330 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
1c340 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
1c350 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
1c360 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
1c370 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c380 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
1c390 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30  allbacks {H12910
1c3a0 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
1c3b0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f   This routine co
1c3c0 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62  nfigures a callb
1c3d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74  ack function - t
1c3e0 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63  he.** progress c
1c3f0 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69  allback - that i
1c400 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  s invoked period
1c410 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
1c420 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61  ng.** running ca
1c430 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1c440 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
1c450 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a  3_step()] and.**
1c460 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1c470 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d  ble()].  An exam
1c480 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
1c490 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1c4a0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
1c4b0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
1c4c0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
1c4d0 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  ** If the progre
1c4e0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
1c4f0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1c500 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
1c510 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
1c520 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
1c530 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
1c540 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
1c550 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
1c560 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
1c570 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
1c580 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1c590 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ler must not do 
1c5a0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1c5b0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1c5c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c5d0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1c5e0 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
1c5f0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
1c600 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1c610 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1c620 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1c630 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1c640 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1c650 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1c660 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1c670 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1c680 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1c690 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1c6a0 2a 20 7b 48 31 32 39 31 31 7d 20 54 68 65 20 63  * {H12911} The c
1c6b0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1c6c0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1c6d0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1c6e0 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20  handler().**    
1c6f0 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64        is invoked
1c700 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
1c710 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
1c720 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20  g calls to.**   
1c730 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1c740 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  step()]..**.** {
1c750 48 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67  H12912} The prog
1c760 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73  ress callback is
1c770 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
1c780 72 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61  r every N virtua
1c790 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61  l.**          ma
1c7a0 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77  chine opcodes, w
1c7b0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
1c7c0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
1c7d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1c7e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65   [sqlite3_progre
1c7f0 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61  ss_handler()] ca
1c800 6c 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72  ll that register
1c810 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
1c820 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66  he callback.  If
1c830 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
1c840 31 2c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  1, sqlite3_progr
1c850 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a  ess_handler().**
1c860 20 20 20 20 20 20 20 20 20 20 61 63 74 73 20 61            acts a
1c870 73 20 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67  s if a NULL prog
1c880 72 65 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64  ress handler had
1c890 20 62 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e   been specified.
1c8a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20  .**.** {H12913} 
1c8b0 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  The progress cal
1c8c0 6c 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20  lback itself is 
1c8d0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
1c8e0 65 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20  e third.**      
1c8f0 20 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20      argument to 
1c900 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1c910 5f 68 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a  _handler()..**.*
1c920 2a 20 7b 48 31 32 39 31 34 7d 20 54 68 65 20 66  * {H12914} The f
1c930 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
1c940 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  o sqlite3_progre
1c950 73 73 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20  ss_handler() is 
1c960 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f  a.**          vo
1c970 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  id pointer passe
1c980 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73  d to the progres
1c990 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  s callback.**   
1c9a0 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
1c9b0 65 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20  each time it is 
1c9c0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
1c9d0 48 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c  H12915} If a cal
1c9e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
1c9f0 65 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e  ep()] results in
1ca00 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70   fewer than N op
1ca10 63 6f 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  codes.**        
1ca20 20 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64    being executed
1ca30 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  , then the progr
1ca40 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ess callback is 
1ca50 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a  never invoked..*
1ca60 2a 0a 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45 76  *.** {H12916} Ev
1ca70 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ery call to [sql
1ca80 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1ca90 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20  ndler()].**     
1caa0 20 20 20 20 20 6f 76 65 72 77 72 69 74 65 73 20       overwrites 
1cab0 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72  any previously r
1cac0 65 67 69 73 74 65 72 65 64 20 70 72 6f 67 72 65  egistered progre
1cad0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  ss handler..**.*
1cae0 2a 20 7b 48 31 32 39 31 37 7d 20 49 66 20 74 68  * {H12917} If th
1caf0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1cb00 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  er callback is N
1cb10 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67  ULL then no prog
1cb20 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ress.**         
1cb30 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f   handler is invo
1cb40 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ked..**.** {H129
1cb50 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72  18} If the progr
1cb60 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
1cb70 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74  urns a result ot
1cb80 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e  her than 0, then
1cb90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1cba0 20 62 65 68 61 76 69 6f 72 20 69 73 20 61 20 69   behavior is a i
1cbb0 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  f [sqlite3_inter
1cbc0 72 75 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e  rupt()] had been
1cbd0 20 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20   called..**     
1cbe0 20 20 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f       <S30500>.*/
1cbf0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
1cc00 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
1cc10 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
1cc20 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
1cc30 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1cc40 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
1cc50 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
1cc60 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d  nection {H12700}
1cc70 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S40200>.**.** 
1cc80 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1cc90 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
1cca0 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73  tabase file whos
1ccb0 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20  e name is given 
1ccc0 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  by the.** filena
1ccd0 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65  me argument. The
1cce0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1ccf0 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
1cd00 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
1cd10 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1cd20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1cd30 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
1cd40 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1cd50 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
1cd60 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
1cd70 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61  n16(). A [databa
1cd80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1cd90 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
1cda0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
1cdb0 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
1cdc0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
1cdd0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
1cde0 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
1cdf0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
1ce00 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
1ce10 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1ce20 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1ce30 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
1ce40 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
1ce50 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
1ce60 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
1ce70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
1ce80 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65  * object. If the
1ce90 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1cea0 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
1ceb0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
1cec0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
1ced0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
1cee0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
1cef0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1cf00 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
1cf10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1cf20 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
1cf30 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
1cf40 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
1cf50 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
1cf60 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
1cf70 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
1cf80 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a   of the error..*
1cf90 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
1cfa0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
1cfb0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1cfc0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
1cfd0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1cfe0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1cff0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
1d000 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
1d010 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1d020 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
1d030 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
1d040 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
1d050 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
1d060 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
1d070 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
1d080 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
1d090 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
1d0a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1d0b0 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
1d0c0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
1d0d0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
1d0e0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
1d0f0 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
1d100 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
1d110 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1d120 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
1d130 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
1d140 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
1d150 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
1d160 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
1d170 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
1d180 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
1d190 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
1d1a0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
1d1b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
1d1c0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
1d1d0 74 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  ter can take one
1d1e0 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
1d1f0 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
1d200 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
1d210 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
1d220 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1d230 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51  _NOMUTEX] or [SQ
1d240 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1d250 54 45 58 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a  TEX] flags:.**.*
1d260 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53  * <dl>.** <dt>[S
1d270 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1d280 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
1d290 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1d2a0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
1d2b0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
1d2c0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1d2d0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
1d2e0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1d2f0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1d300 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  >.**.** <dt>[SQL
1d310 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1d320 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1d330 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1d340 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1d350 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1d360 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
1d370 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
1d380 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
1d390 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1d3a0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1d3b0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
1d3c0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
1d3d0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
1d3e0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
1d3f0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
1d400 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a   returned.</dd>.
1d410 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54  **.** <dt>[SQLIT
1d420 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1d430 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
1d440 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
1d450 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1d460 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1d470 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1d480 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
1d490 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20  tes it if.** it 
1d4a0 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
1d4b0 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
1d4c0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
1d4d0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
1d4e0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1d4f0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1d500 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
1d510 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  >.** </dl>.**.**
1d520 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
1d530 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1d540 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
1d550 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
1d560 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
1d570 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20  wn above or one 
1d580 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69  of the combinati
1d590 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
1d5a0 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68  combined.** with
1d5b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1d5c0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53  N_NOMUTEX] or [S
1d5d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1d5e0 55 54 45 58 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20  UTEX] flags,.** 
1d5f0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1d600 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
1d610 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51  **.** If the [SQ
1d620 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1d630 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
1d640 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1d650 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1d660 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
1d670 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
1d680 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
1d690 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
1d6a0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
1d6b0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
1d6c0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1d6d0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
1d6e0 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   If the.** [SQLI
1d6f0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1d700 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
1d710 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1d720 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
1d730 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
1d740 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
1d750 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
1d760 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
1d770 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1d780 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
1d790 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1d7a0 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  -time..**.** If 
1d7b0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1d7c0 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
1d7d0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1d7e0 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
1d7f0 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
1d800 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
1d810 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73  onnection.  This
1d820 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1d830 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
1d840 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
1d850 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1d860 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
1d870 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1d880 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
1d890 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
1d8a0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
1d8b0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
1d8c0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
1d8d0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
1d8e0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1d8f0 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
1d900 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
1d910 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
1d920 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
1d930 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
1d940 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
1d950 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
1d960 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
1d970 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
1d980 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
1d990 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  ** If the filena
1d9a0 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
1d9b0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
1d9c0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1d9d0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
1d9e0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1d9f0 61 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76  ated.  This priv
1da00 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
1da10 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
1da20 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
1da30 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
1da40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1da50 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
1da60 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  * The fourth par
1da70 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1da80 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
1da90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
1daa0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
1dab0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
1dac0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
1dad0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
1dae0 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
1daf0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
1db00 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
1db10 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72 74  e.  If the fourt
1db20 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
1db30 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1db40 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
1db50 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1db60 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
1db70 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
1db80 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
1db90 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
1dba0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
1dbb0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1dbc0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
1dbd0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1dbe0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
1dbf0 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
1dc00 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
1dc10 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
1dc20 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
1dc30 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
1dc40 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
1dc50 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
1dc60 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
1dc70 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
1dc80 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
1dc90 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
1dca0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
1dcb0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
1dcc0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1dcd0 2a 20 7b 48 31 32 37 30 31 7d 20 54 68 65 20 5b  * {H12701} The [
1dce0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1dcf0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1dd00 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ()], and.**     
1dd10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
1dd20 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
1dd30 63 65 73 20 63 72 65 61 74 65 20 61 20 6e 65 77  ces create a new
1dd40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
1dd50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1dd60 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  n] associated wi
1dd70 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
1dd80 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
1dd90 20 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72 20   given in their 
1dda0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1ddb0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 32 7d 20  .**.** {H12702} 
1ddc0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
1ddd0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
1dde0 65 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a  eted as UTF-8.**
1ddf0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b 73            for [s
1de00 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61  qlite3_open()] a
1de10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
1de20 5f 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54  _v2()] and as UT
1de30 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20  F-16.**         
1de40 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1de50 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73  yte order for [s
1de60 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1de70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 33 7d  ..**.** {H12703}
1de80 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
1de90 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
1dea0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1deb0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1dec0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1ded0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1dee0 32 28 29 5d 20 77 72 69 74 65 73 20 61 20 70 6f  2()] writes a po
1def0 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a  inter to a new.*
1df00 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
1df10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1df20 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a   into *ppDb..**.
1df30 2a 2a 20 7b 48 31 32 37 30 34 7d 20 54 68 65 20  ** {H12704} The 
1df40 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1df50 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1df60 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20  6()], and.**    
1df70 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
1df80 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
1df90 61 63 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  aces return [SQL
1dfa0 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63  ITE_OK] upon suc
1dfb0 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20  cess,.**        
1dfc0 20 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69    or an appropri
1dfd0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
1dfe0 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a   on failure..**.
1dff0 2a 2a 20 7b 48 31 32 37 30 36 7d 20 54 68 65 20  ** {H12706} The 
1e000 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63  default text enc
1e010 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20  oding for a new 
1e020 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64  database created
1e030 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
1e040 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
1e050 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1e060 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20  open_v2()] will 
1e070 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  be UTF-8..**.** 
1e080 7b 48 31 32 37 30 37 7d 20 54 68 65 20 64 65 66  {H12707} The def
1e090 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69  ault text encodi
1e0a0 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74  ng for a new dat
1e0b0 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73  abase created us
1e0c0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
1e0d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1e0e0 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  )] will be UTF-1
1e0f0 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 39  6..**.** {H12709
1e100 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  } The [sqlite3_o
1e110 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72 66  pen(F,D)] interf
1e120 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ace is equivalen
1e130 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  t to.**         
1e140 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1e150 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72  2(F,D,G,0)] wher
1e160 65 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  e the G paramete
1e170 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  r is.**         
1e180 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
1e190 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45  ADWRITE]|[SQLITE
1e1a0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a  _OPEN_CREATE]..*
1e1b0 2a 0a 2a 2a 20 7b 48 31 32 37 31 31 7d 20 49 66  *.** {H12711} If
1e1c0 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
1e1d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1e1e0 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63  n_v2(F,D,G,V)] c
1e1f0 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20  ontains the.**  
1e200 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
1e210 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
1e220 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68  EADONLY] then th
1e230 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1e240 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ened.**         
1e250 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c   for reading onl
1e260 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 32  y..**.** {H12712
1e270 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1e280 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1e290 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
1e2a0 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  )] contains the.
1e2b0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
1e2c0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
1e2d0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 74 68  EN_READWRITE] th
1e2e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1e2f0 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20  is opened.**    
1e300 20 20 20 20 20 20 72 65 61 64 69 6e 67 20 61 6e        reading an
1e310 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
1e320 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65  sible, or for re
1e330 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68  ading only if th
1e340 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  e.**          fi
1e350 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
1e360 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
1e370 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a  rating system..*
1e380 2a 0a 2a 2a 20 7b 48 31 32 37 31 33 7d 20 49 66  *.** {H12713} If
1e390 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
1e3a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1e3b0 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f  n_v2(F,D,G,V)] o
1e3c0 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  mits the.**     
1e3d0 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1e3e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1e3f0 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61  TE] and the data
1e400 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1e410 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f            previo
1e420 75 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65  usly exist, an e
1e430 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1e440 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 34 7d  ..**.** {H12714}
1e450 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
1e460 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1e470 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
1e480 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  ] contains the.*
1e490 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76  *          bit v
1e4a0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  alue [SQLITE_OPE
1e4b0 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68  N_CREATE] and th
1e4c0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
1e4d0 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  not.**          
1e4e0 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74  previously exist
1e4f0 2c 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70  , then an attemp
1e500 74 20 69 73 20 6d 61 64 65 20 74 6f 20 63 72 65  t is made to cre
1e510 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ate and.**      
1e520 20 20 20 20 69 6e 69 74 69 61 6c 69 7a 65 20 74      initialize t
1e530 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a  he database..**.
1e540 2a 2a 20 7b 48 31 32 37 31 37 7d 20 49 66 20 74  ** {H12717} If t
1e550 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1e560 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1e570 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1e580 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
1e590 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
1e5a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1e5b0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1e5c0 74 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 2c  then an private,
1e5d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68  .**          eph
1e5e0 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72  emeral, in-memor
1e5f0 79 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72  y database is cr
1e600 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
1e610 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20  nnection..**    
1e620 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53        <todo>Is S
1e630 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1e640 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  E|SQLITE_OPEN_RE
1e650 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64  ADWRITE required
1e660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
1e670 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1e680 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  )?</todo>.**.** 
1e690 7b 48 31 32 37 31 39 7d 20 49 66 20 74 68 65 20  {H12719} If the 
1e6a0 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c  filename is NULL
1e6b0 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72   or an empty str
1e6c0 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
1e6d0 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ate,.**         
1e6e0 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69   ephemeral on-di
1e6f0 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
1e700 20 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20   be created..** 
1e710 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49           <todo>I
1e720 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  s SQLITE_OPEN_CR
1e730 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e  EATE|SQLITE_OPEN
1e740 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69  _READWRITE requi
1e750 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
1e760 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  in sqlite3_open_
1e770 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  v2()?</todo>.**.
1e780 2a 2a 20 7b 48 31 32 37 32 31 7d 20 54 68 65 20  ** {H12721} The 
1e790 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1e7a0 74 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62 79  tion] created by
1e7b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1e7c0 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20  2(F,D,G,V)].**  
1e7d0 20 20 20 20 20 20 20 20 77 69 6c 6c 20 75 73 65          will use
1e7e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1e7f0 73 5d 20 6f 62 6a 65 63 74 20 69 64 65 6e 74 69  s] object identi
1e800 66 69 65 64 20 62 79 20 74 68 65 20 56 20 70 61  fied by the V pa
1e810 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20 20 20 20  rameter,.**     
1e820 20 20 20 20 20 6f 72 20 74 68 65 20 64 65 66 61       or the defa
1e830 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1e840 5d 20 6f 62 6a 65 63 74 20 69 66 20 56 20 69 73  ] object if V is
1e850 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1e860 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 33 7d 20  .**.** {H12723} 
1e870 54 77 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f  Two [database co
1e880 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20  nnections] will 
1e890 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63  share a common c
1e8a0 61 63 68 65 20 69 66 20 62 6f 74 68 20 77 65 72  ache if both wer
1e8b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70  e.**          op
1e8c0 65 6e 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ened with the sa
1e8d0 6d 65 20 56 46 53 20 77 68 69 6c 65 20 5b 73 68  me VFS while [sh
1e8e0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1e8f0 20 77 61 73 20 65 6e 61 62 6c 65 64 20 61 6e 64   was enabled and
1e900 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20  .**          if 
1e910 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65 73 20 63  both filenames c
1e920 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 75 73 69  ompare equal usi
1e930 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61 66 74 65  ng memcmp() afte
1e940 72 20 68 61 76 69 6e 67 20 62 65 65 6e 0a 2a 2a  r having been.**
1e950 20 20 20 20 20 20 20 20 20 20 70 72 6f 63 65 73            proces
1e960 73 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  sed by the [sqli
1e970 74 65 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c 50  te3_vfs | xFullP
1e980 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64 20  athname] method 
1e990 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a 2f 0a 69  of the VFS..*/.i
1e9a0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
1e9b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
1e9c0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1e9d0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1e9e0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
1e9f0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
1ea00 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1ea10 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1ea20 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1ea30 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
1ea40 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
1ea50 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1ea60 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
1ea70 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1ea80 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
1ea90 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1eaa0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
1eab0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1eac0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
1ead0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1eae0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1eaf0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
1eb00 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
1eb10 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1eb20 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1eb30 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
1eb40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
1eb50 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
1eb60 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
1eb70 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
1eb80 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
1eb90 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
1eba0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
1ebb0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48   And Messages {H
1ebc0 31 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a  12800} <S60200>.
1ebd0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1ebe0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
1ebf0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1ec00 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
1ec10 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
1ec20 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1ec30 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1ec40 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
1ec50 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
1ec60 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
1ec70 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1ec80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
1ec90 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
1eca0 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
1ecb0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1ecc0 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
1ecd0 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
1ece0 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
1ecf0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1ed00 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 54  is undefined.  T
1ed10 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
1ed20 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
1ed30 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
1ed40 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
1ed50 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
1ed60 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
1ed70 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
1ed80 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
1ed90 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
1eda0 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
1edb0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  led..**.** The s
1edc0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
1edd0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
1ede0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
1edf0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
1ee00 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
1ee10 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
1ee20 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1ee30 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
1ee40 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f  ctively..** Memo
1ee50 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
1ee60 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
1ee70 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
1ee80 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
1ee90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1eea0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
1eeb0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
1eec0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
1eed0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
1eee0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
1eef0 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
1ef00 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
1ef10 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
1ef20 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
1ef30 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
1ef40 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
1ef50 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
1ef60 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1ef70 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
1ef80 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
1ef90 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
1efa0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
1efb0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
1efc0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
1efd0 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
1efe0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
1eff0 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
1f000 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
1f010 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
1f020 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
1f030 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
1f040 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
1f050 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
1f060 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
1f070 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
1f080 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
1f090 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
1f0a0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
1f0b0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
1f0c0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
1f0d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f0e0 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
1f0f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
1f100 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
1f110 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
1f120 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
1f130 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
1f140 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
1f150 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
1f160 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
1f170 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
1f180 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
1f190 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
1f1a0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
1f1b0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
1f1c0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
1f1d0 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
1f1e0 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
1f1f0 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
1f200 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
1f210 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
1f220 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
1f230 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
1f240 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
1f250 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
1f260 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
1f270 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  et..**.** INVARI
1f280 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
1f290 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  801} The [sqlite
1f2a0 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e  3_errcode(D)] in
1f2b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1f2c0 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  the numeric.**  
1f2d0 20 20 20 20 20 20 20 20 5b 72 65 73 75 6c 74 20          [result 
1f2e0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
1f2f0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1f300 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
1f310 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ently.**        
1f320 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61    failed interfa
1f330 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  ce call associat
1f340 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
1f350 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f360 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38  ] D..**.** {H128
1f370 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  02} The [sqlite3
1f380 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1f390 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(D)] interface 
1f3a0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
1f3b0 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ric.**          
1f3c0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1f3d0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
1f3e0 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20  ost recently.** 
1f3f0 20 20 20 20 20 20 20 20 20 66 61 69 6c 65 64 20           failed 
1f400 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61  interface call a
1f410 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1f420 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1f430 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
1f440 2a 20 7b 48 31 32 38 30 33 7d 20 54 68 65 20 5b  * {H12803} The [
1f450 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44  sqlite3_errmsg(D
1f460 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1f470 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20  errmsg16(D)].** 
1f480 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
1f490 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  ces return Engli
1f4a0 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
1f4b0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 0a   that describes.
1f4c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1f4d0 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73  error in the mos
1f4e0 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69  tly recently fai
1f4f0 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61  led interface ca
1f500 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ll,.**          
1f510 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74 68 65  encoded as eithe
1f520 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1f530 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
1f540 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54  **.** {H12807} T
1f550 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1f560 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1f570 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73  errmsg()] and [s
1f580 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1f590 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1f5a0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  re valid until t
1f5b0 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69  he next SQLite i
1f5c0 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a  nterface call..*
1f5d0 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43 61  *.** {H12808} Ca
1f5e0 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69  lls to API routi
1f5f0 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  nes that do not 
1f600 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20  return an error 
1f610 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  code.**         
1f620 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69   (example: [sqli
1f630 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29  te3_data_count()
1f640 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20  ]) do not.**    
1f650 20 20 20 20 20 20 63 68 61 6e 67 65 20 74 68 65        change the
1f660 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d   error code or m
1f670 65 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20  essage returned 
1f680 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  by.**          [
1f690 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1f6a0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  )], [sqlite3_ext
1f6b0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
1f6c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
1f6d0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1f6e0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  , or [sqlite3_er
1f6f0 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rmsg16()]..**.**
1f700 20 7b 48 31 32 38 30 39 7d 20 49 6e 74 65 72 66   {H12809} Interf
1f710 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f  aces that are no
1f720 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
1f730 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  h a specific.** 
1f740 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1f750 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
1f760 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20  examples:.**    
1f770 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
1f780 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71  printf()] or [sq
1f790 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1f7a0 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20  red_cache()].** 
1f7b0 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20           do not 
1f7c0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
1f7d0 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
1f7e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1f7f0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
1f800 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1f810 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
1f820 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1f830 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20  3_errmsg()], or 
1f840 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1f850 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
1f860 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
1f870 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
1f880 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1f890 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1f8a0 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
1f8b0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1f8c0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
1f8d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1f8e0 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
1f8f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1f900 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
1f910 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30  nt Object {H1300
1f920 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b  0} <H13010>.** K
1f930 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
1f940 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
1f950 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f960 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
1f970 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
1f980 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
1f990 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
1f9a0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
1f9b0 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
1f9c0 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
1f9d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f9e0 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
1f9f0 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
1fa00 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
1fa10 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
1fa20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
1fa30 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
1fa40 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
1fa50 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
1fa60 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1fa70 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
1fa80 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1fa90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1faa0 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
1fab0 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
1fac0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
1fad0 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
1fae0 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
1faf0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1fb00 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
1fb10 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
1fb20 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
1fb30 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1fb40 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
1fb50 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
1fb60 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
1fb70 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1fb80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1fb90 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
1fba0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
1fbb0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
1fbc0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1fbd0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
1fbe0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1fbf0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1fc00 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
1fc10 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
1fc20 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
1fc30 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
1fc40 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
1fc50 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1fc60 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
1fc70 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
1fc80 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
1fc90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fca0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
1fcb0 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30  ts {H12760} <S20
1fcc0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
1fcd0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1fce0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
1fcf0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
1fd00 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
1fd10 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
1fd20 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
1fd30 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
1fd40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1fd50 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
1fd60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
1fd70 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
1fd80 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
1fd90 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1fda0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
1fdb0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
1fdc0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
1fdd0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
1fde0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
1fdf0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
1fe00 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
1fe10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1fe20 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
1fe30 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20  that construct. 
1fe40 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   The function re
1fe50 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69  turns the old li
1fe60 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  mit..**.** If th
1fe70 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
1fe80 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
1fe90 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
1fea0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72  nchanged..** For
1feb0 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67   the limit categ
1fec0 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49  ory of SQLITE_LI
1fed0 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73  MIT_XYZ there is
1fee0 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
1fef0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
1ff00 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61 20 63  d].** set by a c
1ff10 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72  ompile-time C pr
1ff20 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1ff30 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69   named .** [limi
1ff40 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
1ff50 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  XYZ]..** (The "_
1ff60 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
1ff70 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
1ff80 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41  o "_MAX_".).** A
1ff90 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1ffa0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1ffb0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1ffc0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1ffd0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1ffe0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1fff0 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20  er limit..**.** 
20000 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run time limits 
20010 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
20020 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
20030 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
20040 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
20050 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
20060 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
20070 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
20080 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
20090 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
200a0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
200b0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
200c0 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
200d0 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72 20 74  .** webbrowser t
200e0 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
200f0 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
20100 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
20110 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
20120 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
20130 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
20140 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
20150 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
20160 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
20170 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
20180 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
20190 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
201a0 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
201b0 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
201c0 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
201d0 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
201e0 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
201f0 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
20200 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
20210 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
20220 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
20230 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
20240 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
20250 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
20260 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
20270 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
20280 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
20290 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
202a0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
202b0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
202c0 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
202d0 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
202e0 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
202f0 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
20300 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
20310 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
20320 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
20330 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
20340 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
20350 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
20360 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
20370 2a 20 7b 48 31 32 37 36 32 7d 20 41 20 73 75 63  * {H12762} A suc
20380 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
20390 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
203a0 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69  ,C,V)] where V i
203b0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  s.**          po
203c0 73 69 74 69 76 65 20 63 68 61 6e 67 65 73 20 74  sitive changes t
203d0 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  he limit on the 
203e0 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63  size of construc
203f0 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  t C in the.**   
20400 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
20410 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74   connection] D t
20420 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20  o the lesser of 
20430 56 20 61 6e 64 20 74 68 65 20 68 61 72 64 20 75  V and the hard u
20440 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  pper.**         
20450 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69   bound on the si
20460 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69 73 20  ze of C that is 
20470 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
20480 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ime..**.** {H127
20490 36 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  66} A successful
204a0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
204b0 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20  3_limit(D,C,V)] 
204c0 77 68 65 72 65 20 56 20 69 73 20 6e 65 67 61 74  where V is negat
204d0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
204e0 6c 65 61 76 65 73 20 74 68 65 20 73 74 61 74 65  leaves the state
204f0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
20500 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
20510 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  unchanged..**.**
20520 20 7b 48 31 32 37 36 39 7d 20 41 20 73 75 63 63   {H12769} A succ
20530 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
20540 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c  sqlite3_limit(D,
20550 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68  C,V)] returns th
20560 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  e.**          va
20570 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
20580 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20   on the size of 
20590 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 74  construct C in t
205a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
205b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
205c0 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73  ion] D as it was
205d0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61   prior to the ca
205e0 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ll..*/.int sqlit
205f0 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
20600 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
20610 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
20620 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
20630 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
20640 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32  es {H12790} <H12
20650 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  760>.** KEYWORDS
20660 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
20670 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  y} {limit catego
20680 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
20690 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
206a0 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70 65 63  ne various aspec
206b0 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62 61 73  ts of a [databas
206c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
206d0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 69 6d   that can be lim
206e0 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62 79 20  ited in size by 
206f0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
20700 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
20710 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
20720 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
20730 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73  s are as follows
20740 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  :.**.** <dl>.** 
20750 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
20760 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
20770 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20780 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
20790 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
207a0 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a  ble row.<dd>.**.
207b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
207c0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
207d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
207e0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
207f0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
20800 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
20810 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
20820 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
20830 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
20840 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
20850 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
20860 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
20870 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
20880 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74 68 65   a SELECT or the
20890 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
208a0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
208b0 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
208c0 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
208d0 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
208e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
208f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
20900 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
20910 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
20920 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
20930 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
20940 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  pression.</dd>.*
20950 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
20960 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
20970 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
20980 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
20990 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
209a0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
209b0 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
209c0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
209d0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
209e0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
209f0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
20a00 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
20a10 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
20a20 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
20a30 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
20a40 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
20a50 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
20a60 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
20a70 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
20a80 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20a90 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
20aa0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
20ab0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  unction.</dd>.**
20ac0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
20ad0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
20ae0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20af0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
20b00 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
20b10 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  es.</dd>.**.** <
20b20 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
20b30 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
20b40 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
20b50 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
20b60 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
20b70 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
20b80 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f  e LIKE or.** GLO
20b90 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  B operators.</dd
20ba0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
20bb0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
20bc0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
20bd0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20be0 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61   number of varia
20bf0 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73  bles in an SQL s
20c00 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61  tatement that ca
20c10 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f  n.** be bound.</
20c20 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  dd>.** </dl>.*/.
20c30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
20c40 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
20c50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
20c60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20c70 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
20c80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20c90 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
20ca0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
20cb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20cc0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
20cd0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
20ce0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
20cf0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
20d00 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
20d10 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
20d20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
20d30 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
20d40 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
20d50 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
20d60 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
20d70 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
20d80 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
20d90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
20da0 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
20db0 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
20dc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
20dd0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
20de0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
20df0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
20e00 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
20e10 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a          9../*.**
20e20 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
20e30 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
20e40 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c  ement {H13010} <
20e50 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10000>.** KEYWO
20e60 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
20e70 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
20e80 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
20e90 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
20ea0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
20eb0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
20ec0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
20ed0 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
20ee0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
20ef0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
20f00 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
20f10 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
20f20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
20f30 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
20f40 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ior call to [sql
20f50 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
20f60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20f70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
20f80 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  en16()]..**.** T
20f90 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
20fa0 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
20fb0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
20fc0 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
20fd0 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
20fe0 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
20ff0 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
21000 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
21010 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21020 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
21030 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
21040 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
21050 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
21060 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
21070 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
21080 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65  .** If the nByte
21090 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
210a0 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
210b0 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
210c0 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
210d0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
210e0 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e  r. If nByte is n
210f0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
21100 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
21110 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
21120 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
21130 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42  m zSql.  When nB
21140 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
21150 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
21160 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
21170 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
21180 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
21190 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
211a0 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
211b0 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
211c0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
211d0 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
211e0 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
211f0 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
21200 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
21210 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
21220 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
21230 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
21240 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
21250 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
21260 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
21270 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
21280 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
21290 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
212a0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
212b0 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
212c0 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
212d0 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61  tes..**.** *pzTa
212e0 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
212f0 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
21300 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65   byte past the e
21310 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  nd of the.** fir
21320 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
21330 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
21340 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63   routines only c
21350 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
21360 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
21370 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
21380 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
21390 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69  ng to what remai
213a0 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64  ns.** uncompiled
213b0 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20  ..**.** *ppStmt 
213c0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
213d0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
213e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
213f0 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
21400 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
21410 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
21420 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  )].  If there is
21430 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
21440 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
21450 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e  NULL.  If the in
21460 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
21470 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
21480 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
21490 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
214a0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
214b0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
214c0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30  o NULL..** {A130
214d0 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  18} The calling 
214e0 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
214f0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
21500 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
21510 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
21520 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
21530 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
21540 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
21550 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
21560 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
21570 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
21580 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69  eturned, otherwi
21590 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
215a0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
215b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
215c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
215d0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
215e0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
215f0 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
21600 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
21610 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
21620 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
21630 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
21640 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
21650 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
21660 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
21670 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
21680 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22  ..** In the "v2"
21690 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
216a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
216b0 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
216c0 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
216d0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
216e0 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
216f0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
21700 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
21710 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
21720 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21730 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
21740 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65  * behave a diffe
21750 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61  rently in two wa
21760 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
21770 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65  * <li>.** If the
21780 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
21790 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
217a0 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
217b0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
217c0 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
217d0 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
217e0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
217f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
21800 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
21810 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
21820 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
21830 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73  again.  If the s
21840 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65  chema has change
21850 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68  d in.** a way th
21860 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61  at makes the sta
21870 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72  tement no longer
21880 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33   valid, [sqlite3
21890 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74  _step()] will st
218a0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
218b0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20  QLITE_SCHEMA].  
218c0 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c  But unlike the l
218d0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20  egacy behavior, 
218e0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
218f0 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61  is.** now a fata
21900 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e  l error.  Callin
21910 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
21920 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77  re_v2()] again w
21930 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65  ill not make the
21940 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61  .** error go awa
21950 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73  y.  Note: use [s
21960 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
21970 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78   to find the tex
21980 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73  t.** of the pars
21990 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72  ing error that r
219a0 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51  esults in an [SQ
219b0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74  LITE_SCHEMA] ret
219c0 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  urn..** </li>.**
219d0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e  .** <li>.** When
219e0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
219f0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
21a00 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
21a10 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
21a20 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
21a30 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
21a40 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
21a50 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
21a60 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
21a70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21a80 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
21a90 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
21aa0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
21ab0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79  lt code.** and y
21ac0 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  ou would have to
21ad0 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
21ae0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
21af0 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65  reset()] in orde
21b00 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  r.** to find the
21b10 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
21b20 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
21b30 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
21b40 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
21b50 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
21b60 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
21b70 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
21b80 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
21b90 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ly..** </li>.** 
21ba0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  </ol>.**.** INVA
21bb0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
21bc0 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69  13011} The [sqli
21bd0 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a  te3_prepare(db,z
21be0 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a  Sql,...)] and.**
21bf0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
21c00 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
21c10 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ,zSql,...)] inte
21c20 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74  rfaces interpret
21c30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
21c40 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a   text in their z
21c50 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73  Sql parameter as
21c60 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
21c70 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  13012} The [sqli
21c80 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 64 62  te3_prepare16(db
21c90 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a  ,zSql,...)] and.
21ca0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
21cb0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
21cc0 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20  2(db,zSql,...)] 
21cd0 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72  interfaces inter
21ce0 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  pret the.**     
21cf0 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65       text in the
21d00 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65  ir zSql paramete
21d10 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  r as UTF-16 in t
21d20 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
21d30 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  rder..**.** {H13
21d40 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74  013} If the nByt
21d50 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  e argument to [s
21d60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21d70 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  2(db,zSql,nByte,
21d80 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
21d90 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e    and its varian
21da0 74 73 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  ts is less than 
21db0 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c 20 74 65  zero, the SQL te
21dc0 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  xt is.**        
21dd0 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c    read from zSql
21de0 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
21df0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
21e00 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
21e10 7b 48 31 33 30 31 34 7d 20 49 66 20 74 68 65 20  {H13014} If the 
21e20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74  nByte argument t
21e30 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
21e40 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42  re_v2(db,zSql,nB
21e50 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  yte,...)].**    
21e60 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61        and its va
21e70 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65  riants is non-ne
21e80 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20  gative, then at 
21e90 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65  most nBytes byte
21ea0 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
21eb0 20 53 51 4c 20 74 65 78 74 20 69 73 20 72 65 61   SQL text is rea
21ec0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a  d from zSql..**.
21ed0 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49 6e 20 5b  ** {H13015} In [
21ee0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21ef0 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70  v2(db,zSql,N,P,p
21f00 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 73 20  zTail)] and its 
21f10 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20  variants.**     
21f20 20 20 20 20 20 69 66 20 74 68 65 20 7a 53 71 6c       if the zSql
21f30 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
21f40 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  ains more than o
21f50 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ne SQL statement
21f60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
21f70 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
21f80 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69  ULL, then *pzTai
21f90 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
21fa0 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  nt to the.**    
21fb0 20 20 20 20 20 20 66 69 72 73 74 20 62 79 74 65        first byte
21fc0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
21fd0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
21fe0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
21ff0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74  ..**          <t
22000 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a 70  odo>What does *p
22010 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69  zTail point to i
22020 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 20 73  f there is one s
22030 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e  tatement?</todo>
22040 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 36 7d 20  .**.** {H13016} 
22050 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
22060 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  l to [sqlite3_pr
22070 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
22080 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a  ,N,ppStmt,...)].
22090 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 6f  **          or o
220a0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
220b0 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f 20 2a  ts writes into *
220c0 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 65 72  ppStmt a pointer
220d0 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20   to a new.**    
220e0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
220f0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20  statement] or a 
22100 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20  pointer to NULL 
22110 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73  if zSql contains
22120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74  .**          not
22130 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
22140 77 68 69 74 65 73 70 61 63 65 20 6f 72 20 63 6f  whitespace or co
22150 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  mments..**.** {H
22160 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69  13019} The [sqli
22170 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
22180 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20  ] interface and 
22190 69 74 73 20 76 61 72 69 61 6e 74 73 20 72 65 74  its variants ret
221a0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
221b0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61  [SQLITE_OK] or a
221c0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
221d0 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20  rror code] upon 
221e0 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b  failure..**.** {
221f0 48 31 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b  H13021} Before [
22200 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
22210 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70  db,zSql,nByte,pp
22220 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72  Stmt,pzTail)] or
22230 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   its.**         
22240 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
22250 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20  s an error (any 
22260 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
22270 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a   [SQLITE_OK]),.*
22280 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 79 20  *          they 
22290 66 69 72 73 74 20 73 65 74 20 2a 70 70 53 74 6d  first set *ppStm
222a0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  t to NULL..*/.in
222b0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
222c0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
222d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
222e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
222f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
22300 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
22310 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
22320 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
22330 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
22340 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
22350 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
22360 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
22370 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
22380 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
22390 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
223a0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
223b0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
223c0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
223d0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
223e0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
223f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
22400 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
22410 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
22420 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
22430 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
22440 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
22450 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
22460 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
22470 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
22480 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
22490 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
224a0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
224b0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
224c0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
224d0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
224e0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
224f0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
22500 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
22510 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
22520 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
22530 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
22540 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
22550 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
22560 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
22570 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
22580 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
22590 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
225a0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
225b0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
225c0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
225d0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
225e0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
225f0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
22600 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
22610 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
22620 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
22630 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
22640 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
22650 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
22660 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
22670 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
22680 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
22690 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
226a0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
226b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
226c0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
226d0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
226e0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
226f0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
22700 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
22710 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
22720 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
22730 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
22740 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
22750 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
22760 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
22770 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
22780 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
22790 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
227a0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
227b0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
227c0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
227d0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
227e0 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20  g Statement SQL 
227f0 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30  {H13100} <H13000
22800 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  >.**.** This int
22810 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
22820 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
22830 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
22840 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
22850 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
22860 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
22870 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
22880 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
22890 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
228a0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
228b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
228c0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
228d0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
228e0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
228f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 31  S:.**.** {H13101
22900 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72  } If the [prepar
22910 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61  ed statement] pa
22920 73 73 65 64 20 61 73 20 74 68 65 20 61 72 67 75  ssed as the argu
22930 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  ment to.**      
22940 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c      [sqlite3_sql
22950 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ()] was compiled
22960 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
22970 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22980 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  2()] or.**      
22990 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
229a0 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 74 68  pare16_v2()], th
229b0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28  en [sqlite3_sql(
229c0 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  )] returns.**   
229d0 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72         a pointer
229e0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
229f0 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e  nated string con
22a00 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20  taining a UTF-8 
22a10 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20  rendering.**    
22a20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69        of the ori
22a30 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d  ginal SQL statem
22a40 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31  ent..**.** {H131
22a50 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70  02} If the [prep
22a60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22a70 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72  passed as the ar
22a80 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20  gument to.**    
22a90 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
22aa0 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c  ql()] was compil
22ab0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
22ac0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22ad0 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
22ae0 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
22af0 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 5b  are16()], then [
22b00 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72  sqlite3_sql()] r
22b10 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
22b20 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  inter..**.** {H1
22b30 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e 67  3103} The string
22b40 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
22b50 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69 73  lite3_sql(S)] is
22b60 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
22b70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
22b80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22b90 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64 20 75  ] S is deleted u
22ba0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
22bb0 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63  nalize(S)]..*/.c
22bc0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
22bd0 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
22be0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
22bf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
22c00 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
22c10 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48 31  Value Object {H1
22c20 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  5000} <S20200>.*
22c30 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
22c40 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
22c50 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
22c60 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
22c70 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
22c80 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
22c90 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
22ca0 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
22cb0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
22cc0 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
22cd0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
22ce0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
22cf0 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
22d00 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
22d10 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20 73  stores. Values s
22d20 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
22d30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
22d40 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
22d50 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
22d60 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
22d70 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
22d80 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
22d90 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
22da0 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
22db0 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
22dc0 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
22dd0 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
22de0 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
22df0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
22e00 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
22e10 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
22e20 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
22e30 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
22e40 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
22e50 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
22e60 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
22e70 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
22e80 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
22e90 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
22ea0 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
22eb0 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
22ec0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
22ed0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
22ee0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
22ef0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
22f00 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
22f10 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
22f20 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20  tex is held.  A 
22f30 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
22f40 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
22f50 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
22f60 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
22f70 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
22f80 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
22f90 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
22fa0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
22fb0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
22fc0 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
22fd0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
22fe0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
22ff0 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
23000 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
23010 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
23020 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
23030 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
23040 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
23050 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
23060 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
23070 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
23080 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
23090 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
230a0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
230b0 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
230c0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
230d0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
230e0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
230f0 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
23100 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
23110 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
23120 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
23130 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
23140 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
23150 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
23160 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
23170 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
23180 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
23190 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  en between prote
231a0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
231b0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
231c0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
231d0 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
231e0 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
231f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23200 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
23210 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
23220 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
23230 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
23240 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
23250 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
23260 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
23270 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
23280 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
23290 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
232a0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
232b0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
232c0 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
232d0 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
232e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
232f0 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
23300 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
23310 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
23320 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
23330 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
23340 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
23350 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
23360 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
23370 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
23380 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
23390 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
233a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
233b0 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
233c0 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
233d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
233e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
233f0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
23400 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36 30  ext Object {H160
23410 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  01} <S20200>.**.
23420 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
23430 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
23440 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
23450 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
23460 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
23470 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70  ext object.  A p
23480 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
23490 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
234a0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
234b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
234c0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
234d0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
234e0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
234f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
23500 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
23510 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
23520 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
23530 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
23540 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
23550 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
23560 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
23570 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
23580 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
23590 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
235a0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
235b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
235c0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
235d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
235e0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
235f0 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
23600 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
23610 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
23620 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
23630 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
23640 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
23650 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
23660 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
23670 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30  tatements {H1350
23680 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b  0} <S70300>.** K
23690 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
236a0 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
236b0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
236c0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
236d0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
236e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
236f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
23700 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
23710 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ng}.**.** In the
23720 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70   SQL strings inp
23730 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
23740 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
23750 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
23760 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
23770 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
23780 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65  parameter in one
23790 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a   of these forms:
237a0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
237b0 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
237c0 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
237d0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
237e0 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
237f0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
23800 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66   the parameter f
23810 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  orms shown above
23820 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67   NNN is an integ
23830 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
23840 6e 64 20 56 56 56 20 69 73 20 61 6e 20 61 6c 70  nd VVV is an alp
23850 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d  ha-numeric param
23860 65 74 65 72 20 6e 61 6d 65 2e 20 54 68 65 20 76  eter name. The v
23870 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
23880 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
23890 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
238a0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
238b0 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
238c0 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
238d0 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
238e0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
238f0 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
23900 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  here..**.** The 
23910 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
23920 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
23930 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
23940 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
23950 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
23960 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
23970 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
23980 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
23990 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
239a0 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
239b0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
239c0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
239d0 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
239e0 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
239f0 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d  et..** The leftm
23a00 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
23a10 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
23a20 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73  f 1.  When the s
23a30 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
23a40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
23a50 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
23a60 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
23a70 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
23a80 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
23a90 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
23aa0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
23ab0 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65  nce..** The inde
23ac0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
23ad0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
23ae0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
23af0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
23b00 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
23b10 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
23b20 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78  ired.  The index
23b30 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
23b40 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
23b50 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
23b60 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20  * The NNN value 
23b70 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
23b80 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
23b90 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
23ba0 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
23bb0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
23bc0 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
23bd0 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
23be0 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
23bf0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
23c00 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
23c10 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
23c20 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75  .** In those rou
23c30 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
23c40 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
23c50 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
23c60 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
23c70 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
23c80 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
23c90 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
23ca0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
23cb0 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
23cc0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
23cd0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
23ce0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
23cf0 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
23d00 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
23d10 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68  tive, the length
23d20 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
23d30 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
23d40 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
23d50 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
23d60 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
23d70 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
23d80 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
23d90 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
23da0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
23db0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
23dc0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
23dd0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
23de0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
23df0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
23e00 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
23e10 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
23e20 77 69 74 68 20 69 74 2e 20 49 66 20 74 68 65 20  with it. If the 
23e30 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
23e40 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
23e50 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
23e60 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
23e70 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
23e80 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
23e90 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
23ea0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
23eb0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
23ec0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
23ed0 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74 68  .** If the fifth
23ee0 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
23ef0 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
23f00 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
23f10 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
23f20 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
23f30 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
23f40 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
23f50 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
23f60 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
23f70 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
23f80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23f90 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
23fa0 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
23fb0 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
23fc0 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
23fd0 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
23fe0 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65    A zeroblob use
23ff0 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
24000 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
24010 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
24020 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
24030 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
24040 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
24050 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
24060 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
24070 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
24080 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
24090 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
240a0 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
240b0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
240c0 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
240d0 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
240e0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20   routines..** A 
240f0 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
24100 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
24110 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
24120 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
24130 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
24140 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
24150 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
24160 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69  d after.** [sqli
24170 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
24180 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69 61  ] (and its varia
24190 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33  nts) or [sqlite3
241a0 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a  _reset()] and.**
241b0 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   before [sqlite3
241c0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e  _step()]..** Bin
241d0 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
241e0 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
241f0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
24200 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75  outine..** Unbou
24210 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
24220 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
24230 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
24240 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
24250 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
24260 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20  n success or an 
24270 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a  error code if.**
24280 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
24290 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52  rong.  [SQLITE_R
242a0 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
242b0 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
242c0 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
242d0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53  ut of range.  [S
242e0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
242f0 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
24300 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b  oc() fails..** [
24310 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
24320 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
24330 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   if these routin
24340 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e  es are called on
24350 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61   a.** virtual ma
24360 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74 68  chine that is th
24370 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72  e wrong state or
24380 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65 61   which has alrea
24390 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  dy been finalize
243a0 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20  d..** Detection 
243b0 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72  of misuse is unr
243c0 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63  eliable.  Applic
243d0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
243e0 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53  t depend.** on S
243f0 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74  QLITE_MISUSE ret
24400 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49  urns.  SQLITE_MI
24410 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64  SUSE is intended
24420 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a   to indicate a.*
24430 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  * a logic error 
24440 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  in the applicati
24450 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  on.  Future vers
24460 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
24470 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61  ight.** panic ra
24480 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e  ther than return
24490 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
244a0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
244b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
244c0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
244d0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
244e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
244f0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
24500 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
24510 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
24520 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
24530 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54 68 65  .** {H13506} The
24540 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   [SQL statement 
24550 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e  compiler] recogn
24560 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66 20 74  izes tokens of t
24570 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 20 20  he forms.**     
24580 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22       "?", "?NNN"
24590 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22  , "$VVV", ":VVV"
245a0 2c 20 61 6e 64 20 22 40 56 56 56 22 20 61 73 20  , and "@VVV" as 
245b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2c 0a  SQL parameters,.
245c0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72  **          wher
245d0 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71  e NNN is any seq
245e0 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20  uence of one or 
245f0 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a 20 20  more digits.**  
24600 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 72          and wher
24610 65 20 56 56 56 20 69 73 20 61 6e 79 20 73 65 71  e VVV is any seq
24620 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20  uence of one or 
24630 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65 72 69  more alphanumeri
24640 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68  c.**          ch
24650 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22  aracters or "::"
24660 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c   optionally foll
24670 6f 77 65 64 20 62 79 20 61 20 73 74 72 69 6e 67  owed by a string
24680 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20   containing.**  
24690 20 20 20 20 20 20 20 20 6e 6f 20 73 70 61 63 65          no space
246a0 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20  s and contained 
246b0 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73  within parenthes
246c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30  es..**.** {H1350
246d0 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76  9} The initial v
246e0 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70  alue of an SQL p
246f0 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
24700 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 32 7d  ..**.** {H13512}
24710 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
24720 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74   "?" SQL paramet
24730 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72  er is one larger
24740 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20   than the.**    
24750 20 20 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e        largest in
24760 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d  dex of SQL param
24770 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74  eter to the left
24780 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20  , or 1 if.**    
24790 20 20 20 20 20 20 74 68 65 20 22 3f 22 20 69 73        the "?" is
247a0 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51   the leftmost SQ
247b0 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  L parameter..**.
247c0 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54 68 65 20  ** {H13515} The 
247d0 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e  index of an "?NN
247e0 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  N" SQL parameter
247f0 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72 20   is the integer 
24800 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  NNN..**.** {H135
24810 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  18} The index of
24820 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56   an ":VVV", "$VV
24830 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51  V", or "@VVV" SQ
24840 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  L parameter is.*
24850 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
24860 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65 78  ame as the index
24870 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63   of leftmost occ
24880 75 72 72 65 6e 63 65 73 20 6f 66 20 74 68 65 20  urrences of the 
24890 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
248a0 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f   parameter, or o
248b0 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65  ne more than the
248c0 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
248d0 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ver all.**      
248e0 20 20 20 20 70 61 72 61 6d 65 74 65 72 73 20 74      parameters t
248f0 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20 74 68  o the left if th
24900 69 73 20 69 73 20 74 68 65 20 66 69 72 73 74 20  is is the first 
24910 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20  occurrence.**   
24920 20 20 20 20 20 20 20 6f 66 20 74 68 69 73 20 70         of this p
24930 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69  arameter, or 1 i
24940 66 20 74 68 69 73 20 69 73 20 74 68 65 20 6c 65  f this is the le
24950 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72  ftmost parameter
24960 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 31 7d  ..**.** {H13521}
24970 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d   The [SQL statem
24980 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61  ent compiler] fa
24990 69 6c 73 20 77 69 74 68 20 61 6e 20 5b 53 51 4c  ils with an [SQL
249a0 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20 20  ITE_RANGE].**   
249b0 20 20 20 20 20 20 20 65 72 72 6f 72 20 69 66 20         error if 
249c0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
249d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
249e0 20 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a 2a 20   less than 1.** 
249f0 20 20 20 20 20 20 20 20 20 6f 72 20 67 72 65 61           or grea
24a00 74 65 72 20 74 68 61 6e 20 74 68 65 20 63 6f 6d  ter than the com
24a10 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49 54 45  pile-time SQLITE
24a20 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55  _MAX_VARIABLE_NU
24a30 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20 20 20 20  MBER.**         
24a40 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
24a50 2a 20 7b 48 31 33 35 32 34 7d 20 43 61 6c 6c 73  * {H13524} Calls
24a60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
24a70 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
24a80 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29  _bind(S,N,V,...)
24a90 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  ].**          as
24aa0 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c 75  sociate the valu
24ab0 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51 4c  e V with all SQL
24ac0 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76 69   parameters havi
24ad0 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ng an.**        
24ae0 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e 20    index of N in 
24af0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24b00 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
24b10 2a 20 7b 48 31 33 35 32 37 7d 20 43 61 6c 6c 73  * {H13527} Calls
24b20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
24b30 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
24b40 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a  _bind(S,N,...)].
24b50 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72  **          over
24b60 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c 73  ride prior calls
24b70 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76   with the same v
24b80 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20 4e  alues of S and N
24b90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 30 7d  ..**.** {H13530}
24ba0 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62 6c   Bindings establ
24bb0 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74 65  ished by [sqlite
24bc0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
24bd0 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e  lite3_bind(S,...
24be0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  )].**          p
24bf0 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63 61  ersist across ca
24c00 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
24c10 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a  reset(S)]..**.**
24c20 20 7b 48 31 33 35 33 33 7d 20 49 6e 20 63 61 6c   {H13533} In cal
24c30 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
24c40 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
24c50 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
24c60 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
24c70 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
24c80 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
24c90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
24ca0 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
24cb0 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 74  ] SQLite binds t
24cc0 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20 20  he first L.**   
24cd0 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66 20         bytes of 
24ce0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
24cf0 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
24d00 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20 20   V, when L.**   
24d10 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e 65         is non-ne
24d20 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
24d30 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73 20  13536} In calls 
24d40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
24d50 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
24d60 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
24d70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
24d80 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
24d90 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 63  ] SQLite binds c
24da0 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20 20  haracters.**    
24db0 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68 72        from V thr
24dc0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
24dd0 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77 68  ero character wh
24de0 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65  en L is negative
24df0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 39 7d  ..**.** {H13539}
24e00 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
24e10 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
24e20 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
24e30 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
24e40 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
24e50 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
24e60 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
24e70 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
24e80 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
24e90 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a  is the special.*
24ea0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  *          const
24eb0 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  ant [SQLITE_STAT
24ec0 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73 75  IC], SQLite assu
24ed0 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61 6c  mes that the val
24ee0 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20 20  ue V.**         
24ef0 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61 74   is held in stat
24f00 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  ic unmanaged spa
24f10 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f 74  ce that will not
24f20 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20   change.**      
24f30 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20 6c      during the l
24f40 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 62  ifetime of the b
24f50 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  inding..**.** {H
24f60 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73 20  13542} In calls 
24f70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
24f80 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _blob(S,N,V,L,D)
24f90 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
24fa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
24fb0 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f  t(S,N,V,L,D)], o
24fc0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
24fd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24fe0 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77  16(S,N,V,L,D)] w
24ff0 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65  hen D is the spe
25000 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  cial.**         
25010 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
25020 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
25030 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20  e routine makes 
25040 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  a.**          pr
25050 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
25060 65 20 76 61 6c 75 65 20 56 20 62 65 66 6f 72 65  e value V before
25070 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
25080 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e 20 63  ** {H13545} In c
25090 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
250a0 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56  _bind_blob(S,N,V
250b0 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,L,D)],.**      
250c0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
250d0 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
250e0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
250f0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
25100 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
25110 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20  D)] when D is a 
25120 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20  pointer to.**   
25130 20 20 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f         a functio
25140 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  n, SQLite invoke
25150 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  s that function 
25160 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a  to destroy the.*
25170 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
25180 20 56 20 61 66 74 65 72 20 69 74 20 68 61 73 20   V after it has 
25190 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
251a0 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  he value V..**.*
251b0 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e 20 63 61  * {H13548} In ca
251c0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
251d0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c  bind_zeroblob(S,
251e0 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75  N,V,L)] the valu
251f0 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20  e bound.**      
25200 20 20 20 20 69 73 20 61 20 42 4c 4f 42 20 6f 66      is a BLOB of
25210 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a   L bytes, or a z
25220 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
25230 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65  if L is negative
25240 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35 31 7d  ..**.** {H13551}
25250 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
25260 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
25270 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61  (S,N,V)] the V a
25280 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20  rgument may.**  
25290 20 20 20 20 20 20 20 20 62 65 20 65 69 74 68 65          be eithe
252a0 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73  r a [protected s
252b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
252c0 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20  ject or an.**   
252d0 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63         [unprotec
252e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
252f0 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e  e] object..*/.in
25300 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
25310 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
25320 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
25330 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
25340 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
25350 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
25360 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
25370 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
25380 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
25390 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
253a0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
253b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
253c0 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
253d0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
253e0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
253f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
25400 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
25410 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
25420 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
25430 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
25440 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
25450 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
25460 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
25470 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
25480 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25490 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
254a0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
254b0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
254c0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
254d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
254e0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
254f0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
25500 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
25510 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25520 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
25530 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
25540 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
25550 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d 20  meters {H13600} 
25560 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70300>.**.** T
25570 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
25580 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
25590 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
255a0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
255b0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
255c0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
255d0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
255e0 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
255f0 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
25600 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
25610 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
25620 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
25630 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
25640 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
25650 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
25660 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
25670 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
25680 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
25690 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
256a0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
256b0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
256c0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
256d0 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
256e0 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
256f0 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
25700 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
25710 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
25720 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
25730 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
25740 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
25750 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75  f the ?NNN are u
25760 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
25770 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
25780 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   list..**.** See
25790 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
257a0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
257b0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
257c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
257d0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
257e0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
257f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
25800 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
25810 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
25820 7b 48 31 33 36 30 31 7d 20 54 68 65 20 5b 73 71  {H13601} The [sq
25830 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25840 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69  eter_count(S)] i
25850 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
25870 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
25880 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65  f all SQL parame
25890 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ters in the.**  
258a0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
258b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20  d statement] S, 
258c0 6f 72 20 30 20 69 66 20 53 20 63 6f 6e 74 61 69  or 0 if S contai
258d0 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65  ns no SQL parame
258e0 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ters..*/.int sql
258f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
25900 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
25910 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
25920 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
25930 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
25940 74 65 72 20 7b 48 31 33 36 32 30 7d 20 3c 53 37  ter {H13620} <S7
25950 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0300>.**.** This
25960 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
25970 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
25980 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d  e name of the n-
25990 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d  th.** [SQL param
259a0 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72 65 70  eter] in a [prep
259b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
259c0 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
259d0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
259e0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
259f0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
25a00 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
25a10 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
25a20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
25a30 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
25a40 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
25a50 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
25a60 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
25a70 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
25a80 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
25a90 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
25aa0 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
25ab0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61  he name..** Para
25ac0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
25ad0 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
25ae0 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
25af0 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
25b00 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 6f 20  ** and are also 
25b10 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
25b20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
25b30 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ters"..**.** The
25b40 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
25b50 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
25b60 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
25b70 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c  **.** If the val
25b80 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue n is out of r
25b90 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e  ange or if the n
25ba0 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
25bb0 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
25bc0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
25bd0 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e  ned.  The return
25be0 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
25bf0 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
25c00 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
25c10 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
25c20 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
25c30 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
25c40 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
25c50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25c60 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
25c70 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
25c80 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
25c90 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
25ca0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
25cb0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
25cc0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25cd0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
25ce0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
25cf0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
25d00 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
25d10 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
25d20 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  13621} The [sqli
25d30 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25d40 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  er_name(S,N)] in
25d50 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
25d60 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 55 54  **          a UT
25d70 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
25d80 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25d90 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
25da0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
25db0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25dc0 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67 20  ement] S having 
25dd0 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20  index N, or.**  
25de0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66 20          NULL if 
25df0 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c 20  there is no SQL 
25e00 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69  parameter with i
25e10 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68 65  ndex N or if the
25e20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
25e30 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65  ameter with inde
25e40 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d  x N is an anonym
25e50 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20 22 3f  ous parameter "?
25e60 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  "..*/.const char
25e70 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
25e80 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
25e90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25ea0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25eb0 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
25ec0 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
25ed0 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36  Given Name {H136
25ee0 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  40} <S70300>.**.
25ef0 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e  ** Return the in
25f00 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
25f10 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
25f20 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20  s name.  The.** 
25f30 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
25f40 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
25f50 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
25f60 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
25f70 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
25f80 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
25f90 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65  3_bind()].  A ze
25fa0 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
25fb0 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
25fc0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
25fd0 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65  und.  The parame
25fe0 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
25ff0 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
26000 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
26010 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
26020 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
26030 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
26040 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
26050 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
26060 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
26070 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
26080 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
26090 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
260a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
260b0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
260c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
260d0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
260e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
260f0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
26100 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3641} The [sqlit
26110 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
26120 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e  r_index(S,N)] in
26130 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
26140 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
26150 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72  index of SQL par
26160 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 5b 70  ameter in the [p
26170 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26180 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  t].**          S
26190 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63   whose name matc
261a0 68 65 73 20 74 68 65 20 55 54 46 2d 38 20 73 74  hes the UTF-8 st
261b0 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66 20  ring N, or 0 if 
261c0 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 20 20  there is.**     
261d0 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a       no match..*
261e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
261f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
26200 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
26210 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
26220 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
26230 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
26240 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
26250 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
26260 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 33  t {H13660} <S703
26270 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  00>.**.** Contra
26280 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
26290 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
262a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
262b0 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
262c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
262d0 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
262e0 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
262f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
26300 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69  * Use this routi
26310 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
26320 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
26330 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49  to NULL..**.** I
26340 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
26350 20 7b 48 31 33 36 36 31 7d 20 54 68 65 20 5b 73   {H13661} The [s
26360 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
26370 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66  dings(S)] interf
26380 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20 53  ace resets all S
26390 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  QL.**          p
263a0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
263b0 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  s in the [prepar
263c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
263d0 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  back to NULL..*/
263e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
263f0 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
26400 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
26410 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
26420 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
26430 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
26440 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30 3e  H13710} <S10700>
26450 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
26460 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
26470 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
26480 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
26490 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
264a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54  ed statement]. T
264b0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
264c0 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
264d0 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
264e0 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
264f0 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
26500 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
26510 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
26520 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
26530 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54 68 65 20  ** {H13711} The 
26540 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26550 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66  count(S)] interf
26560 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
26570 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20  number of.**    
26580 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69 6e        columns in
26590 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
265a0 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68 65  generated by the
265b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
265c0 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20  ment] S,.**     
265d0 20 20 20 20 20 6f 72 20 30 20 69 66 20 53 20 64       or 0 if S d
265e0 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74 65  oes not generate
265f0 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a   a result set..*
26600 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
26610 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
26620 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
26630 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26640 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
26650 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
26660 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30 3e  H13720} <S10700>
26670 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
26680 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
26690 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
266a0 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
266b0 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
266c0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
266d0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
266e0 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  nt.  The sqlite3
266f0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
26700 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
26710 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
26720 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
26730 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
26740 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
26750 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
26760 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
26770 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
26780 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
26790 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72  string.  The fir
267a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
267b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
267c0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
267d0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
267e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
267f0 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  nt. The second p
26800 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
26810 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
26820 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  .  The leftmost 
26830 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
26840 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65   0..**.** The re
26850 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
26860 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
26870 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
26880 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26890 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
268a0 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
268b0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
268c0 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
268d0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
268e0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
268f0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
26900 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
26910 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
26920 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  *.** If sqlite3_
26930 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
26940 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
26950 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
26960 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
26970 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
26980 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
26990 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
269a0 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
269b0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
269c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ned..**.** The n
269d0 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
269e0 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
269f0 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
26a00 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
26a10 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
26a20 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
26a30 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
26a40 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
26a50 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
26a60 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
26a70 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
26a80 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
26a90 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
26aa0 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
26ab0 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   next..**.** INV
26ac0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
26ad0 48 31 33 37 32 31 7d 20 41 20 73 75 63 63 65 73  H13721} A succes
26ae0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
26af0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
26b00 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29  column_name(S,N)
26b10 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
26b20 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26b30 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
26b40 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72  Nth column (wher
26b50 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  e 0 is.**       
26b60 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20     the leftmost 
26b70 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20  column) for the 
26b80 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
26b90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
26ba0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26bb0 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74  t] S as a zero-t
26bc0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
26bd0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
26be0 31 33 37 32 33 7d 20 41 20 73 75 63 63 65 73 73  13723} A success
26bf0 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
26c00 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
26c10 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e  olumn_name16(S,N
26c20 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
26c30 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26c40 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
26c50 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65   Nth column (whe
26c60 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20  re 0 is.**      
26c70 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74      the leftmost
26c80 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65   column) for the
26c90 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
26ca0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
26cb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26cc0 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d  nt] S as a zero-
26cd0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31  terminated UTF-1
26ce0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  6 string.**     
26cf0 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69       in the nati
26d00 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
26d10 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20 54 68  *.** {H13724} Th
26d20 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
26d30 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73  n_name()] and [s
26d40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
26d50 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  me16()].**      
26d60 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72      interfaces r
26d70 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  eturn a NULL poi
26d80 6e 74 65 72 20 69 66 20 74 68 65 79 20 61 72 65  nter if they are
26d90 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20   unable to.**   
26da0 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20         allocate 
26db0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
26dc0 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75  heir normal retu
26dd0 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a  rn strings..**.*
26de0 2a 20 7b 48 31 33 37 32 35 7d 20 49 66 20 74 68  * {H13725} If th
26df0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
26e00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26e10 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a  _name(S,N)] or.*
26e20 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
26e30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
26e40 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f  6(S,N)] is out o
26e50 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68  f range, then th
26e60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
26e70 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
26e80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
26e90 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d 20 54  **.** {H13726} T
26ea0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
26eb0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
26ec0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29  column_name(S,N)
26ed0 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
26ee0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
26ef0 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61  n_name16(S,N)] a
26f00 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  re valid until t
26f10 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20  he next.**      
26f20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74 68      call to eith
26f30 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  er routine with 
26f40 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20 4e  the same S and N
26f50 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20   parameters.**  
26f60 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c          or until
26f70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
26f80 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
26f90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 37 7d  ..**.** {H13727}
26fa0 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20 63   When a result c
26fb0 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45  olumn of a [SELE
26fc0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  CT] statement co
26fd0 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ntains.**       
26fe0 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2c     an AS clause,
26ff0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61   the name of tha
27000 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
27010 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20  identifier.**   
27020 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 72 69         to the ri
27030 67 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b 65  ght of the AS ke
27040 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  yword..*/.const 
27050 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
27060 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
27070 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
27080 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
27090 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
270a0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
270b0 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
270c0 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
270d0 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
270e0 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33  uery Result {H13
270f0 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  740} <S10700>.**
27100 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
27110 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
27120 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
27130 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77  what column of w
27140 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20  hat.** table in 
27150 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61  which database a
27160 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53 45   result of a [SE
27170 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
27180 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54  comes from..** T
27190 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
271a0 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
271b0 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
271c0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
271d0 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
271e0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
271f0 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65  .  The _database
27200 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
27210 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
27220 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
27230 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
27240 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
27250 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
27260 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
27270 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
27280 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72  n name..** The r
27290 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
272a0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
272b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
272c0 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
272d0 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
272e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
272f0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
27300 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
27310 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
27320 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
27330 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
27340 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72  *.** The names r
27350 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
27360 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
27370 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
27380 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
27390 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
273a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
273b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
273c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73   following calls
273d0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
273e0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54  statement]..** T
273f0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
27400 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
27410 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
27420 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
27430 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
27440 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
27450 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
27460 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
27470 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63  .** If the Nth c
27480 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
27490 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
274a0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
274b0 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
274c0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
274d0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
274e0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
274f0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
27500 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f   NULL.  These ro
27510 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
27520 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
27530 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
27540 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
27550 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  urs.  Otherwise,
27560 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
27570 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
27580 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
27590 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c  table.** and col
275a0 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
275b0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
275c0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
275d0 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61  .**.** As with a
275e0 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
275f0 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74  APIs, those post
27600 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20  fixed with "16" 
27610 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
27620 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
27630 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  , the other func
27640 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
27650 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  -8. {END}.**.** 
27660 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
27670 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
27680 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
27690 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
276a0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
276b0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
276c0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
276d0 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
276e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37  ned..**.** {A137
276f0 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  51}.** If two or
27700 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
27710 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
27720 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
27730 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
27740 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
27750 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
27760 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
27770 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
27780 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
27790 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  fined..**.** INV
277a0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
277b0 48 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71 6c  H13741} The [sql
277c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
277d0 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  base_name(S,N)] 
277e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
277f0 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
27800 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a       the UTF-8 z
27810 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
27820 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
27830 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ase from which t
27840 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
27850 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
27860 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
27870 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
27880 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20  s extracted,.** 
27890 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
278a0 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
278b0 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
278c0 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
278d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
278e0 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
278f0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
27900 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
27910 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20 54 68  *.** {H13742} Th
27920 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
27930 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
27940 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
27950 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
27960 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
27970 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
27980 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74  yte order zero-t
27990 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
279a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
279b0 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
279c0 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65  which the Nth re
279d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
279e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
279f0 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20  tement] S is.** 
27a00 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63 74           extract
27a10 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
27a20 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
27a30 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
27a40 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
27a50 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
27a60 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
27a70 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
27a80 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
27a90 7b 48 31 33 37 34 33 7d 20 54 68 65 20 5b 73 71  {H13743} The [sq
27aa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
27ab0 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  le_name(S,N)] in
27ac0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27ad0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
27ae0 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72     the UTF-8 zer
27af0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
27b00 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66  e of the table f
27b10 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a  rom which the.**
27b20 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
27b30 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
27b40 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
27b50 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74  tement] S is ext
27b60 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20  racted,.**      
27b70 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74      or NULL if t
27b80 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
27b90 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
27ba0 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
27bb0 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
27bc0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
27bd0 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
27be0 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
27bf0 7b 48 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71  {H13744} The [sq
27c00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
27c10 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  le_name16(S,N)] 
27c20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27c30 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
27c40 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
27c50 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
27c60 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  r zero-terminate
27c70 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
27c80 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
27c90 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e  from which the N
27ca0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
27cb0 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
27cc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
27cd0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
27ce0 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
27cf0 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
27d00 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
27d10 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
27d20 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
27d30 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
27d40 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
27d50 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
27d60 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20 54 68  *.** {H13745} Th
27d70 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
27d80 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c  n_origin_name(S,
27d90 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
27da0 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
27db0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
27dc0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
27dd0 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
27de0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d  able column from
27df0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20   which the.**   
27e00 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c         Nth resul
27e10 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
27e20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27e30 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63  ent] S is extrac
27e40 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted,.**         
27e50 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
27e60 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
27e70 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
27e80 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  ression.**      
27e90 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65      or if unable
27ea0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
27eb0 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65  ory to store the
27ec0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   name..**.** {H1
27ed0 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  3746} The [sqlit
27ee0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
27ef0 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e  _name16(S,N)] in
27f00 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27f10 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
27f20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61     the UTF-16 na
27f30 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
27f40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
27f50 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
27f60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
27f70 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20  lumn from which 
27f80 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
27f90 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
27fa0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
27fb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
27fc0 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72  is extracted, or
27fd0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
27fe0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20   column.**      
27ff0 20 20 20 20 6f 66 20 53 20 69 73 20 61 20 67 65      of S is a ge
28000 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
28010 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
28020 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
28030 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
28040 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
28050 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d 20 54  **.** {H13748} T
28060 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  he return values
28070 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20   from.**        
28080 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
28090 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
280a0 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
280b0 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
280c0 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61            are va
280d0 6c 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66 65  lid for the life
280e0 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65  time of the [pre
280f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28100 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
28110 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69  until the encodi
28120 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20 62 79  ng is changed by
28130 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74   another metadat
28140 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  a.**          in
28150 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72  terface call for
28160 20 74 68 65 20 73 61 6d 65 20 70 72 65 70 61 72   the same prepar
28170 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
28180 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 41   column..**.** A
28190 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
281a0 2a 20 7b 41 31 33 37 35 31 7d 20 49 66 20 74 77  * {A13751} If tw
281b0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
281c0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
281d0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  re.**          [
281e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
281f0 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
28200 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
28210 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20  nterfaces].**   
28220 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 73         for the s
28230 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
28240 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
28250 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20  ult column.**   
28260 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73 61         at the sa
28270 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
28280 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
28290 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
282a0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
282b0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
282c0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
282d0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
282e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
282f0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
28300 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
28310 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
28320 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
28330 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
28340 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
28350 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
28360 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
28370 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
28380 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
28390 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
283a0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
283b0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
283c0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
283d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
283e0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
283f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
28400 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
28410 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
28420 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
28430 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 36  ry Result {H1376
28440 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
28450 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
28460 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
28470 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
28480 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
28490 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
284a0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
284b0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
284c0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
284d0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
284e0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
284f0 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
28500 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
28510 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
28520 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
28530 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
28540 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
28550 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  mn is returned. 
28560 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   If the Nth colu
28570 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
28580 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
28590 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
285a0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
285b0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
285c0 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65  urned..** The re
285d0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
285e0 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
285f0 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  coded. {END}.**.
28600 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
28610 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
28620 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
28630 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
28640 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
28650 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
28660 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
28670 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
28680 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
28690 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
286a0 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
286b0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
286c0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
286d0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
286e0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
286f0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
28700 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
28710 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
28720 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
28730 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  =0)..**.** SQLit
28740 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
28750 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
28760 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65   So just because
28770 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
28780 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
28790 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
287a0 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
287b0 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
287c0 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
287d0 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
287e0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
287f0 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
28800 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
28810 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
28820 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
28830 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a  static.  Type.**
28840 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
28850 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
28860 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
28870 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
28880 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
28890 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a  hose values..**.
288a0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
288b0 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20 20 41  *.** {H13761}  A
288c0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
288d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
288e0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e  umn_decltype(S,N
288f0 29 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20  )] returns a.** 
28900 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
28910 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
28920 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
28930 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64  g the declared d
28940 61 74 61 74 79 70 65 0a 2a 2a 20 20 20 20 20 20  atatype.**      
28950 20 20 20 20 20 6f 66 20 74 68 65 20 74 61 62 6c       of the tabl
28960 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70  e column that ap
28970 70 65 61 72 73 20 61 73 20 74 68 65 20 4e 74 68  pears as the Nth
28980 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65   column (numbere
28990 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66  d.**           f
289a0 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65  rom 0) of the re
289b0 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 20  sult set to the 
289c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
289d0 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ent] S..**.** {H
289e0 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 65 73  13762}  A succes
289f0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
28a00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
28a10 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a  ltype16(S,N)].**
28a20 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
28a30 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ns a zero-termin
28a40 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  ated UTF-16 nati
28a50 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74  ve byte order st
28a60 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
28a70 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65    containing the
28a80 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79   declared dataty
28a90 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  pe of the table 
28aa0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65  column that appe
28ab0 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ars.**          
28ac0 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   as the Nth colu
28ad0 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f  mn (numbered fro
28ae0 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75  m 0) of the resu
28af0 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a  lt set to the.**
28b00 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70             [prep
28b10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28b20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 33  S..**.** {H13763
28b30 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20  }  If N is less 
28b40 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20 67  than 0 or N is g
28b50 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65  reater than or e
28b60 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20  qual to.**      
28b70 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72 20       the number 
28b80 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
28b90 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28ba0 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20  ement] S,.**    
28bb0 20 20 20 20 20 20 20 6f 72 20 69 66 20 74 68 65         or if the
28bc0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53   Nth column of S
28bd0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
28be0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20 72 61  n or subquery ra
28bf0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
28c00 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20 63    than a table c
28c10 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61 20 6d  olumn, or if a m
28c20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
28c30 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20   failure.**     
28c40 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72        occurs dur
28c50 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e  ing encoding con
28c60 76 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a  versions, then.*
28c70 2a 20 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  *           call
28c80 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  s to [sqlite3_co
28c90 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c  lumn_decltype(S,
28ca0 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  N)] or.**       
28cb0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
28cc0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53  umn_decltype16(S
28cd0 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c  ,N)] return NULL
28ce0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
28cf0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
28d00 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
28d10 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
28d20 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28d30 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
28d40 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
28d50 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
28d60 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
28d70 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
28d80 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 30  t {H13200} <S100
28d90 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  00>.**.** After 
28da0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
28db0 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
28dc0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
28dd0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
28de0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
28df0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
28e00 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
28e10 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
28e20 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
28e30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
28e40 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
28e50 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
28e60 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
28e70 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
28e80 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
28e90 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
28ea0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
28eb0 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
28ec0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
28ed0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
28ee0 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
28ef0 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
28f00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
28f10 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
28f20 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
28f30 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
28f40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28f50 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
28f60 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
28f70 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
28f80 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
28f90 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
28fa0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
28fb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
28fc0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
28fd0 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
28fe0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
28ff0 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
29000 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
29010 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
29020 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
29030 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
29040 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  orted..**.** In 
29050 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
29060 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
29070 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
29080 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
29090 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
290a0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
290b0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
290c0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
290d0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68  MISUSE]..** With
290e0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
290f0 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
29100 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
29110 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
29120 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
29130 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
29140 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
29150 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
29160 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
29170 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
29180 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
29190 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
291a0 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
291b0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
291c0 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61  job.  If the sta
291d0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
291e0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
291f0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
29200 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
29210 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
29220 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
29230 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
29240 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
29250 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
29260 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
29270 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
29280 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
29290 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
292a0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
292b0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
292c0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
292d0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
292e0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
292f0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
29300 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
29310 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
29320 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
29330 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
29340 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
29350 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
29360 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
29370 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
29380 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
29390 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
293a0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
293b0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
293c0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66   state..**.** If
293d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
293e0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
293f0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
29400 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
29410 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
29420 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
29430 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
29440 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
29450 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
29460 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
29470 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
29480 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
29490 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
294a0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
294b0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
294c0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
294d0 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
294e0 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
294f0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  *.** [SQLITE_ERR
29500 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
29510 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
29520 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
29530 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
29540 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
29550 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
29560 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
29570 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
29580 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
29590 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
295a0 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
295b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
295c0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20  msg()]..** With 
295d0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
295e0 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
295f0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
29600 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
29610 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
29620 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
29630 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
29640 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
29650 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
29660 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
29670 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
29680 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
29690 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
296a0 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22  ment].  In the "
296b0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
296c0 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
296d0 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
296e0 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
296f0 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
29700 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
29710 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
29720 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
29730 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
29740 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
29750 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
29760 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
29770 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
29780 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
29790 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
297a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
297b0 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
297c0 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
297d0 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
297e0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
297f0 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
29800 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
29810 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
29820 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
29830 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
29840 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
29850 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
29860 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
29870 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
29880 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
29890 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
298a0 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
298b0 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
298c0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
298d0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
298e0 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
298f0 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
29900 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
29910 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
29920 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
29930 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
29940 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
29950 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
29960 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
29970 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29980 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
29990 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
299a0 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
299b0 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
299c0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
299d0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
299e0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
299f0 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
29a00 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
29a10 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
29a20 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
29a30 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
29a40 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
29a50 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
29a60 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
29a70 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
29a80 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
29a90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
29aa0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
29ab0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
29ac0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
29ad0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
29ae0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
29af0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29b00 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
29b10 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
29b20 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
29b30 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
29b40 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
29b50 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
29b60 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
29b70 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
29b80 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
29b90 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  nded..**.** INVA
29ba0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
29bb0 31 33 32 30 32 7d 20 20 49 66 20 74 68 65 20 5b  13202}  If the [
29bc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29bd0 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 20 74  nt] S is ready t
29be0 6f 20 62 65 20 72 75 6e 2c 20 74 68 65 6e 0a 2a  o be run, then.*
29bf0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
29c00 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61 64  ite3_step(S)] ad
29c10 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 65 70  vances that prep
29c20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
29c30 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntil.**         
29c40 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20    completion or 
29c50 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61 64  until it is read
29c60 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74  y to return anot
29c70 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a  her row of the.*
29c80 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 73 75  *           resu
29c90 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 69 6c  lt set, or until
29ca0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   an [sqlite3_int
29cb0 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75  errupt | interru
29cc0 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  pt].**          
29cd0 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65   or a run-time e
29ce0 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
29cf0 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20 57 68 65  ** {H15304}  Whe
29d00 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  n a call to [sql
29d10 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63 61  ite3_step(S)] ca
29d20 75 73 65 73 20 74 68 65 20 5b 70 72 65 70 61 72  uses the [prepar
29d30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
29d40 20 20 20 20 20 20 20 20 20 20 20 53 20 74 6f 20             S to 
29d50 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
29d60 6e 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  n, the function 
29d70 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
29d80 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  DONE]..**.** {H1
29d90 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63 61  5306}  When a ca
29da0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
29db0 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62 65  tep(S)] stops be
29dc0 63 61 75 73 65 20 69 74 20 69 73 20 72 65 61 64  cause it is read
29dd0 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  y to.**         
29de0 20 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72    return another
29df0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
29e00 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 75 72  lt set, it retur
29e10 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e  ns [SQLITE_ROW].
29e20 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38 7d 20  .**.** {H15308} 
29e30 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   If a call to [s
29e40 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
29e50 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a  encounters an.**
29e60 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
29e70 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20  te3_interrupt | 
29e80 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20  interrupt] or a 
29e90 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a  run-time error,.
29ea0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 20  **           it 
29eb0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
29ec0 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f 64  priate error cod
29ed0 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f 6e  e that is not on
29ee0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
29ef0 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b    [SQLITE_OK], [
29f00 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72 20  SQLITE_ROW], or 
29f10 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a  [SQLITE_DONE]..*
29f20 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20 20 49  *.** {H15310}  I
29f30 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e  f an [sqlite3_in
29f40 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
29f50 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69  upt] or a run-ti
29f60 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20  me error.**     
29f70 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72        occurs dur
29f80 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
29f90 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a  qlite3_step(S)].
29fa0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72  **           for
29fb0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
29fc0 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65  tement] S create
29fd0 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
29fe0 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65       legacy inte
29ff0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
2a000 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a  prepare()] or.**
2a010 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
2a020 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2a030 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74  , then the funct
2a040 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68  ion returns eith
2a050 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
2a060 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2a070 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f  [SQLITE_BUSY], o
2a080 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
2a090 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2a0a0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2a0b0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2a0c0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2a0d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2a0e0 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37 37  esult set {H1377
2a0f0 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
2a100 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * Returns the nu
2a110 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69  mber of values i
2a120 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
2a130 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2a140 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  set..**.** INVAR
2a150 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
2a160 33 37 37 31 7d 20 20 41 66 74 65 72 20 61 20 63  3771}  After a c
2a170 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2a180 73 74 65 70 28 53 29 5d 20 74 68 61 74 20 72 65  step(S)] that re
2a190 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f  turns [SQLITE_RO
2a1a0 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  W],.**          
2a1b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61   the [sqlite3_da
2a1c0 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75  ta_count(S)] rou
2a1d0 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
2a1e0 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 0a   the same value.
2a1f0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20  **           as 
2a200 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
2a210 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75  umn_count(S)] fu
2a220 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nction..**.** {H
2a230 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b 73  13772}  After [s
2a240 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2a250 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e 79  has returned any
2a260 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
2a270 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  n.**           [
2a280 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62  SQLITE_ROW] or b
2a290 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
2a2a0 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65 6e  tep(S)] has been
2a2b0 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 0a 2a   called on the.*
2a2c0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  *           [pre
2a2d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a2e0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 74   for the first t
2a2f0 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73  ime since it was
2a300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
2a310 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
2a320 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20 5b 73   prepared] or [s
2a330 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c 20 72  qlite3_reset | r
2a340 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  eset],.**       
2a350 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
2a360 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20  _data_count(S)] 
2a370 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2a380 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  zero..*/.int sql
2a390 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2a3a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2a3b0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2a3c0 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
2a3d0 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48 31  al Datatypes {H1
2a3e0 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53  0265} <S10110><S
2a3f0 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  10120>.** KEYWOR
2a400 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
2a410 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45  **.** {H10266} E
2a420 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
2a430 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
2a440 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
2a450 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
2a460 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
2a470 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2a480 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
2a490 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
2a4a0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
2a4b0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
2a4c0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
2a4d0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
2a4e0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
2a4f0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
2a500 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
2a510 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
2a520 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2a530 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
2a540 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
2a550 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
2a560 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
2a570 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
2a580 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
2a590 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
2a5a0 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
2a5b0 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
2a5c0 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
2a5d0 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
2a5e0 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
2a5f0 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
2a600 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
2a610 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
2a620 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
2a630 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
2a640 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a650 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
2a660 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
2a670 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
2a680 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
2a690 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
2a6a0 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
2a6b0 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
2a6c0 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
2a6d0 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
2a6e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a6f0 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
2a700 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33 38  om A Query {H138
2a710 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20  00} <S10700>.** 
2a720 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
2a730 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2a740 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2a750 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
2a760 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75  e "result set qu
2a770 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  ery" interface..
2a780 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2a790 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
2a7a0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
2a7b0 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
2a7c0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
2a7d0 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
2a7e0 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79  query.  In every
2a7f0 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
2a800 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2a810 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2a820 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a830 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
2a840 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
2a850 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
2a860 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
2a870 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2a880 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a890 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
2a8a0 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
2a8b0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
2a8c0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2a8d0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2a8e0 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
2a8f0 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
2a900 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54   be returned.  T
2a910 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2a920 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2a930 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
2a940 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ex 0..**.** If t
2a950 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2a960 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
2a970 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
2a980 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
2a990 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
2a9a0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
2a9b0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
2a9c0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2a9d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2a9e0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
2a9f0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
2aa00 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
2aa10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2aa20 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2aa30 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
2aa40 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
2aa50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
2aa60 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2aa70 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
2aa80 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
2aa90 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
2aaa0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2aab0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
2aac0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
2aad0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2aae0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2aaf0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
2ab00 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2ab10 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
2ab20 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
2ab30 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
2ab40 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2ab50 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
2ab60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2ab70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2ab80 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2ab90 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
2aba0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2abb0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
2abc0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
2abd0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2abe0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
2abf0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2ac00 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2ac10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2ac20 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
2ac30 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2ac40 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
2ac50 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2ac60 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
2ac70 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
2ac80 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
2ac90 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72  t column.  The r
2aca0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
2acb0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2acc0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
2acd0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2ace0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
2acf0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
2ad00 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
2ad10 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
2ad20 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2ad30 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2ad40 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
2ad50 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
2ad60 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
2ad70 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
2ad80 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
2ad90 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
2ada0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
2adb0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
2adc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2add0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
2ade0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
2adf0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2ae00 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
2ae10 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
2ae20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2ae30 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
2ae40 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2ae50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
2ae60 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2ae70 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
2ae80 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2ae90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
2aea0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2aeb0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2aec0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2aed0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2aee0 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
2aef0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
2af00 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2af10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2af20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2af30 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
2af40 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2af50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2af60 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ytes..** If the 
2af70 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2af80 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2af90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2afa0 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
2afb0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2afc0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2afd0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2afe0 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
2aff0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2b000 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2b010 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2b020 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
2b030 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
2b040 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
2b050 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20  rminator at the 
2b060 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
2b070 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69  ring.  For clari
2b080 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65  ty: the value re
2b090 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75  turned is the nu
2b0a0 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
2b0b0 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
2b0c0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2b0d0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
2b0e0 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75  .** Strings retu
2b0f0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2b100 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
2b110 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2b120 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
2b130 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
2b140 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
2b150 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54  o terminated.  T
2b160 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2b170 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2b180 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2b190 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2b1a0 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74  BLOB is an arbit
2b1b0 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c  rary.** pointer,
2b1c0 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61   possibly even a
2b1d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2b1e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2b1f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2b200 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
2b210 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  ilar to sqlite3_
2b220 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
2b230 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65  * but leaves the
2b240 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31   result in UTF-1
2b250 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
2b260 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f   order instead o
2b270 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20  f UTF-8..** The 
2b280 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2b290 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
2b2a0 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a  in this count..*
2b2b0 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20  *.** The object 
2b2c0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2b2d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2b2e0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2b2f0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2b300 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2b310 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2b320 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2b330 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2b340 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2b350 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2b360 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2b370 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2b380 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2b390 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2b3a0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2b3b0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2b3c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2b3d0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2b3e0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2b3f0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2b400 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2b410 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2b420 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2b430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2b440 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2b450 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2b460 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2b470 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2b480 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2b490 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2b4a0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2b4b0 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2b4c0 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a  propriate.  For.
2b4d0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
2b4e0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
2b4f0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
2b500 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
2b510 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
2b520 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
2b530 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
2b540 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
2b550 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
2b560 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
2b570 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
2b580 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
2b590 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
2b5a0 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
2b5b0 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
2b5c0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
2b5d0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
2b5e0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
2b5f0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
2b600 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
2b610 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
2b620 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
2b630 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2b640 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2b650 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2b660 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
2b670 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
2b680 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
2b690 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
2b6a0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2b6b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2b6c0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
2b6d0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2b6e0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2b6f0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2b700 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
2b710 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2b720 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2b730 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2b740 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
2b750 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
2b760 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2b770 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
2b780 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2b790 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2b7a0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
2b7b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2b7c0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2b7d0 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
2b7e0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
2b7f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2b800 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2b810 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
2b820 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
2b830 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2b840 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
2b850 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
2b860 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
2b870 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
2b880 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
2b890 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
2b8a0 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
2b8b0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
2b8c0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
2b8d0 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
2b8e0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
2b8f0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2b900 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
2b910 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
2b920 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2b930 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2b940 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
2b950 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2b960 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2b970 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
2b980 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
2b990 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
2b9a0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2b9b0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
2b9c0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
2b9d0 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
2b9e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2b9f0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2ba00 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
2ba10 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
2ba20 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
2ba30 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
2ba40 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ote>.**.** The t
2ba50 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
2ba60 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
2ba70 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
2ba80 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
2ba90 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
2baa0 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
2bab0 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
2bac0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
2bad0 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
2bae0 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
2baf0 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
2bb00 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
2bb10 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
2bb20 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
2bb30 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
2bb40 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
2bb50 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
2bb60 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
2bb70 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
2bb80 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
2bb90 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
2bba0 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
2bbb0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
2bbc0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2bbd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2bbe0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
2bbf0 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
2bc00 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2bc10 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
2bc20 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
2bc30 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
2bc40 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
2bc50 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
2bc60 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
2bc70 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
2bc80 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
2bc90 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2bca0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2bcb0 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
2bcc0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2bcd0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2bce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2bcf0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2bd00 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
2bd10 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
2bd20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
2bd30 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
2bd40 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2bd50 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2bd60 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
2bd70 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2bd80 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
2bd90 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2bda0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2bdb0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2bdc0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2bdd0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2bde0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
2bdf0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2be00 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2be10 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
2be20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2be30 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
2be40 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2be50 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
2be60 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2be70 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2be80 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2be90 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
2bea0 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69  >.**.** Conversi
2beb0 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2bec0 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2bed0 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2bee0 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2bef0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2bf00 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2bf10 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2bf20 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2bf30 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2bf40 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2bf50 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73  r pointer points
2bf60 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65   to will have be
2bf70 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
2bf80 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
2bf90 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
2bfa0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
2bfb0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
2bfc0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
2bfd0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
2bfe0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
2bff0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
2c000 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
2c010 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
2c020 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
2c030 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
2c040 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
2c050 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
2c060 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
2c070 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
2c080 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
2c090 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
2c0a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2c0b0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2c0c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c0d0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2c0e0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2c0f0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
2c100 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2c110 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2c120 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2c130 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2c140 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2c150 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c160 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
2c170 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
2c180 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
2c190 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
2c1a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
2c1b0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2c1c0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
2c1d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c1e0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
2c1f0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
2c200 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
2c210 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
2c220 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2c230 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2c240 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2c250 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
2c260 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
2c270 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
2c280 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
2c290 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
2c2a0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
2c2b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2c2c0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
2c2d0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2c2e0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
2c2f0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
2c300 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2c310 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
2c320 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
2c330 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c340 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ytes()..**.** Th
2c350 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2c360 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
2c370 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
2c380 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
2c390 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
2c3a0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
2c3b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2c3c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c3d0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2c3e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
2c3f0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65   called.  The me
2c400 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
2c410 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
2c420 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
2c430 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
2c440 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
2c450 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
2c460 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
2c470 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2c480 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
2c490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2c4a0 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
2c4b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2c4c0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65  ]..**.** If a me
2c4d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2c4e0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2c4f0 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
2c500 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
2c510 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
2c520 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
2c530 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
2c540 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
2c550 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
2c560 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
2c570 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2c580 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
2c590 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
2c5a0 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
2c5b0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
2c5c0 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
2c5d0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
2c5e0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _NOMEM]..**.** I
2c5f0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2c600 20 7b 48 31 33 38 30 33 7d 20 54 68 65 20 5b 73   {H13803} The [s
2c610 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2c620 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ob(S,N)] interfa
2c630 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2c640 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
2c650 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
2c660 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2c670 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
2c680 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2c690 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c6a0 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 42 4c  ent] S into a BL
2c6b0 4f 42 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  OB and then retu
2c6c0 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  rns a.**        
2c6d0 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65    pointer to the
2c6e0 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65   converted value
2c6f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 36 7d  ..**.** {H13806}
2c700 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2c710 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d  lumn_bytes(S,N)]
2c720 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c730 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
2c740 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
2c750 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f  es in the BLOB o
2c760 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  r string (exclus
2c770 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
2c780 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
2c790 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
2c7a0 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
2c7b0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2c7c0 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
2c7d0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2c7e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c7f0 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20  lob(S,N)] or.** 
2c800 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2c810 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c  3_column_text(S,
2c820 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  N)]..**.** {H138
2c830 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
2c840 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c850 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2c860 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
2c870 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
2c880 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  f bytes in the s
2c890 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
2c8a0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2c8b0 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
2c8c0 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
2c8d0 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
2c8e0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
2c8f0 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
2c900 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2c910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c920 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16(S,N)]..**.** 
2c930 7b 48 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71  {H13812} The [sq
2c940 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
2c950 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ble(S,N)] interf
2c960 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2c970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
2c980 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
2c990 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2c9a0 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
2c9b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c9c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c9d0 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66  ment] S into a f
2c9e0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2c9f0 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  lue and.**      
2ca00 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
2ca10 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65  py of that value
2ca20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 35 7d  ..**.** {H13815}
2ca30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2ca40 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69  lumn_int(S,N)] i
2ca50 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2ca60 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2ca70 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
2ca80 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
2ca90 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2caa0 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
2cab0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2cac0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
2cad0 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65  o a 64-bit signe
2cae0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a  d integer and.**
2caf0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2cb00 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62  s the lower 32 b
2cb10 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65  its of that inte
2cb20 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  ger..**.** {H138
2cb30 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  18} The [sqlite3
2cb40 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c  _column_int64(S,
2cb50 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
2cb60 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2cb70 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2cb80 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2cb90 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2cba0 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
2cbb0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2cbc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cbd0 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  S into a 64-bit 
2cbe0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
2cbf0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
2cc00 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2cc10 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
2cc20 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20 54 68  *.** {H13821} Th
2cc30 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2cc40 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74  n_text(S,N)] int
2cc50 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2cc60 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2cc70 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
2cc80 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
2cc90 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2cca0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2ccb0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2ccc0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
2ccd0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2cce0 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20  d UTF-8.**      
2ccf0 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
2cd00 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2cd10 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
2cd20 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34 7d 20  .**.** {H13824} 
2cd30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
2cd40 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d  umn_text16(S,N)]
2cd50 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2cd60 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2cd70 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
2cd80 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
2cd90 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2cda0 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  set for the.**  
2cdb0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2cdc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2cdd0 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
2cde0 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20  nated 2-byte.** 
2cdf0 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64           aligned
2ce00 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
2ce10 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67  yte order string
2ce20 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2ce30 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74           a point
2ce40 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2ce50 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 37  g..**.** {H13827
2ce60 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2ce70 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d  olumn_type(S,N)]
2ce80 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ce90 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ns.**          o
2cea0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55  ne of [SQLITE_NU
2ceb0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54  LL], [SQLITE_INT
2cec0 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
2ced0 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  LOAT],.**       
2cee0 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d     [SQLITE_TEXT]
2cef0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  , or [SQLITE_BLO
2cf00 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
2cf10 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
2cf20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e    the Nth column
2cf30 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2cf40 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2cf50 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
2cf60 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
2cf70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2cf80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33 30 7d  ..**.** {H13830}
2cf90 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2cfa0 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d  lumn_value(S,N)]
2cfb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2cfc0 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
2cfd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
2cfe0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2cff0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2d000 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
2d010 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
2d020 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2d030 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2d040 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
2d050 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
2d060 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2d070 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
2d080 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d090 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2d0a0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2d0b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2d0c0 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
2d0d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d0e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2d0f0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
2d100 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2d110 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
2d120 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
2d130 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2d140 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2d150 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2d160 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2d170 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
2d180 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2d190 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
2d1a0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2d1b0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
2d1c0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
2d1d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d1e0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2d1f0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
2d200 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d210 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2d220 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d230 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2d240 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2d250 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2d260 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
2d270 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
2d280 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2d290 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d2a0 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
2d2b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
2d2c0 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
2d2d0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
2d2e0 7b 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30 30  {H13300} <S70300
2d2f0 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S30100>.**.** 
2d300 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2d310 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
2d320 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
2d330 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
2d340 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
2d350 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2d360 77 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63  was executed suc
2d370 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74  cessfully or not
2d380 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c   executed at all
2d390 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45  , then.** SQLITE
2d3a0 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
2d3b0 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66   If execution of
2d3c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
2d3d0 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a  ailed then an.**
2d3e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
2d3f0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2d400 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
2d410 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ed..**.** This r
2d420 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
2d430 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
2d440 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65  t during the exe
2d450 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  cution of the.**
2d460 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d470 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76  ment].  If the v
2d480 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68  irtual machine h
2d490 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65  as not.** comple
2d4a0 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68  ted execution wh
2d4b0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
2d4c0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20  is called, that 
2d4d0 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75  is like.** encou
2d4e0 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72  ntering an error
2d4f0 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   or an [sqlite3_
2d500 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65  interrupt | inte
2d510 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d  rrupt]..** Incom
2d520 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61  plete updates ma
2d530 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  y be rolled back
2d540 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e   and transaction
2d550 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64  s canceled,.** d
2d560 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
2d570 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61  circumstances, a
2d580 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72  nd the.** [error
2d590 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20   code] returned 
2d5a0 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  will be [SQLITE_
2d5b0 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ABORT]..**.** IN
2d5c0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2d5d0 7b 48 31 31 33 30 32 7d 20 54 68 65 20 5b 73 71  {H11302} The [sq
2d5e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2d5f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73  )] interface des
2d600 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20 20  troys the.**    
2d610 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2d620 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64  statement] S and
2d630 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a   releases all.**
2d640 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79            memory
2d650 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75 72   and file resour
2d660 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 61 74  ces held by that
2d670 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b   object..**.** {
2d680 48 31 31 33 30 34 7d 20 49 66 20 74 68 65 20 6d  H11304} If the m
2d690 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2d6a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2d6b0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2d6c0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2d6d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2d6e0 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72 6f  returned an erro
2d6f0 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  r,.**          t
2d700 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  hen [sqlite3_fin
2d710 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72 6e  alize(S)] return
2d720 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 72 6f  s that same erro
2d730 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
2d740 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
2d750 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2d760 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d770 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
2d780 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2d790 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53 37  ect {H13330} <S7
2d7a0 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0300>.**.** The 
2d7b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
2d7c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2d7d0 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
2d7e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d7f0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
2d800 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2d810 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
2d820 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
2d830 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74  .** Any SQL stat
2d840 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
2d850 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
2d860 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
2d870 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
2d880 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2d890 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2d8a0 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
2d8b0 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
2d8c0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
2d8d0 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
2d8e0 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
2d8f0 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  gs..**.** {H1133
2d900 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2d910 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2d920 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
2d930 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d940 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20  nt] S.**        
2d950 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65    back to the be
2d960 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
2d970 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rogram..**.** {H
2d980 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f  11334} If the mo
2d990 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2d9a0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2d9b0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  S)] for the.**  
2d9c0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2d9d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
2d9e0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2d9f0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
2da00 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  DONE],.**       
2da10 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65     or if [sqlite
2da20 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
2da30 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
2da40 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
2da50 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
2da60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2da70 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
2da80 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  E_OK]..**.** {H1
2da90 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f 73  1336} If the mos
2daa0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2dab0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2dac0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  )] for the.**   
2dad0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
2dae0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2daf0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
2db00 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
2db10 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65     [sqlite3_rese
2db20 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
2db30 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2db40 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2db50 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b 73   {H11338} The [s
2db60 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2db70 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
2db80 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
2db90 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  alues.**        
2dba0 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65    of any [sqlite
2dbb0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
2dbc0 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
2dbd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2dbe0 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
2dbf0 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
2dc00 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2dc10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2dc20 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
2dc30 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
2dc40 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 30 32  s {H16100} <S202
2dc50 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2dc60 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
2dc70 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
2dc80 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2dc90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2dca0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
2dcb0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2dcc0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2dcd0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
2dce0 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20 66  *.** These two f
2dcf0 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
2dd00 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
2dd10 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
2dd20 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
2dd30 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
2dd40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
2dd50 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
2dd60 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
2dd70 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
2dd80 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
2dd90 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2dda0 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
2ddb0 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65  ifference betwee
2ddc0 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20  n the.** two is 
2ddd0 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
2dde0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e  parameter, the n
2ddf0 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c  ame of the (scal
2de00 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  ar) function or.
2de10 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69 73  ** aggregate, is
2de20 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
2de30 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  8 for sqlite3_cr
2de40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2de50 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f  and UTF-16.** fo
2de60 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2de70 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a  _function16()..*
2de80 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
2de90 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2dea0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2deb0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
2dec0 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
2ded0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
2dee0 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65 20  d.  If a single 
2def0 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72  program uses mor
2df00 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
2df10 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2df20 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68  n internally, th
2df30 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  en SQL functions
2df40 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69   must be added i
2df50 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a  ndividually to.*
2df60 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  * each database 
2df70 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  connection..**.*
2df80 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
2df90 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2dfa0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
2dfb0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
2dfc0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
2dfd0 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67 74  ined.  The lengt
2dfe0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
2dff0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
2e000 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65  bytes, exclusive
2e010 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d   of.** the zero-
2e020 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74  terminator.  Not
2e030 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20  e that the name 
2e040 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
2e050 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a  in bytes, not.**
2e060 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e   characters.  An
2e070 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
2e080 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
2e090 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
2e0a0 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
2e0b0 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   in [SQLITE_ERRO
2e0c0 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  R] being returne
2e0d0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  d..**.** The thi
2e0e0 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
2e0f0 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
2e100 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2e110 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
2e120 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2e130 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 49  gregate takes. I
2e140 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
2e150 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2e160 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
2e170 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2e180 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
2e190 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2e1a0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
2e1b0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2e1c0 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
2e1d0 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
2e1e0 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
2e1f0 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
2e200 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
2e210 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
2e220 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e   parameters.  An
2e230 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
2e240 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
2e250 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20  ould be able to 
2e260 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74  work.** work wit
2e270 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c  h UTF-8, UTF-16l
2e280 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20  e, or UTF-16be. 
2e290 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d   But some implem
2e2a0 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65  entations may be
2e2b0 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65  .** more efficie
2e2c0 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f  nt with one enco
2e2d0 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65  ding than anothe
2e2e0 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65  r.  It is allowe
2e2f0 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
2e300 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2e310 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  nction() or sqli
2e320 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e330 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65  ion16() multiple
2e340 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74  .** times with t
2e350 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2e360 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
2e370 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54  ent values of eT
2e380 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20  extRep..** When 
2e390 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2e3a0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2e3b0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
2e3c0 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
2e3d0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
2e3e0 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
2e3f0 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
2e400 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
2e410 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49  conversion..** I
2e420 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
2e430 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65  a single impleme
2e440 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f  ntation which do
2e450 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74  es not care what
2e460 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e   text.** encodin
2e470 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  g is used, then 
2e480 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
2e490 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53  ent should be [S
2e4a0 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
2e4b0 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72 61  * The fifth para
2e4c0 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
2e4d0 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
2e4e0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
2e4f0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
2e500 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
2e510 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
2e520 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
2e530 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
2e540 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76  ]..**.** The sev
2e550 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64  enth, eighth and
2e560 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
2e570 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
2e580 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
2e590 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
2e5a0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
2e5b0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
2e5c0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2e5d0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2e5e0 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51  ate. A scalar SQ
2e5f0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2e600 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2e610 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
2e620 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
2e630 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly, NULL pointe
2e640 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  rs should be pas
2e650 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
2e660 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
2e670 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67  arameters. An ag
2e680 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2e690 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2e6a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e6b0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
2e6c0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
2e6d0 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
2e6e0 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64   for xFunc. To d
2e6f0 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
2e700 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
2e710 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
2e720 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c  pass NULL for al
2e730 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
2e740 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
2e750 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65  * It is permitte
2e760 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
2e770 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2e780 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2e790 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
2e7a0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
2e7b0 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
2e7c0 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
2e7d0 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
2e7e0 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
2e7f0 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
2e800 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c   encodings.  SQL
2e810 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
2e820 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2e830 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  on most closely 
2e840 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
2e850 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
2e860 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2e870 75 73 65 64 2e 20 20 41 20 66 75 6e 63 74 69 6f  used.  A functio
2e880 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2e890 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
2e8a0 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
2e8b0 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
2e8c0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
2e8d0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2e8e0 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
2e8f0 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
2e900 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65    A function whe
2e910 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
2e920 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
2e930 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
2e940 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
2e950 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
2e960 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
2e970 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
2e980 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
2e990 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66 75 6e  rent.  .** A fun
2e9a0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2e9b0 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
2e9c0 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
2e9d0 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
2e9e0 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
2e9f0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
2ea00 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2ea10 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2ea20 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
2ea30 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
2ea40 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74 2d  16..**.** Built-
2ea50 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
2ea60 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
2ea70 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
2ea80 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2ea90 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ons..** The firs
2eaa0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  t application-de
2eab0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77  fined function w
2eac0 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65  ith a given name
2ead0 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a   overrides all.*
2eae0 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74  * built-in funct
2eaf0 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65  ions in the same
2eb00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2eb10 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20  ction] with the 
2eb20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53 75  same name..** Su
2eb30 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61  bsequent applica
2eb40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2eb50 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ctions of the sa
2eb60 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65  me name only ove
2eb70 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20  rride .** prior 
2eb80 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2eb90 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ned functions th
2eba0 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 74 20  at are an exact 
2ebb0 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a  match for the.**
2ebc0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d   number of param
2ebd0 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 65 72  eters and prefer
2ebe0 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  red encoding..**
2ebf0 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61 74 69  .** An applicati
2ec00 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2ec10 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
2ec20 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
2ec30 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
2ec40 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
2ec50 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
2ec60 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
2ec70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2ec80 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
2ec90 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
2eca0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2ecb0 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
2ecc0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2ecd0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ning..**.** INVA
2ece0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
2ecf0 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  16103} The [sqli
2ed00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ed10 69 6f 6e 31 36 28 44 2c 58 2c 2e 2e 2e 29 5d 20  ion16(D,X,...)] 
2ed20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2ed30 62 65 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20  behave.**       
2ed40 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63     as [sqlite3_c
2ed50 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2ed60 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 20 65 76 65 72  ,X,...)] in ever
2ed70 79 20 77 61 79 20 65 78 63 65 70 74 20 74 68 61  y way except tha
2ed80 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  t it.**         
2ed90 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2eda0 58 20 61 72 67 75 6d 65 6e 74 20 61 73 20 7a 65  X argument as ze
2edb0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2edc0 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20  F-16.**         
2edd0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2ede0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 73  er instead of as
2edf0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2ee00 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
2ee10 31 36 31 30 36 7d 20 41 20 73 75 63 63 65 73 73  16106} A success
2ee20 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
2ee30 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2ee40 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
2ee50 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2ee60 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ,E,...)] interfa
2ee70 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74 65  ce shall registe
2ee80 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  r.**          or
2ee90 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61   replaces callba
2eea0 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20  ck functions in 
2eeb0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2eec0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20  nnection] D.**  
2eed0 20 20 20 20 20 20 20 20 75 73 65 64 20 74 6f 20          used to 
2eee0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2eef0 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64  L function named
2ef00 20 58 20 77 69 74 68 20 4e 20 70 61 72 61 6d 65   X with N parame
2ef10 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
2ef20 20 61 6e 64 20 68 61 76 69 6e 67 20 61 20 70 72   and having a pr
2ef30 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2ef40 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a  oding of E..**.*
2ef50 2a 20 7b 48 31 36 31 30 39 7d 20 41 20 73 75 63  * {H16109} A suc
2ef60 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2ef70 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ef80 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2ef90 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20  ,P,F,S,L)].**   
2efa0 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 70         shall rep
2efb0 6c 61 63 65 20 74 68 65 20 50 2c 20 46 2c 20 53  lace the P, F, S
2efc0 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66  , and L values f
2efd0 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61  rom any prior ca
2efe0 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  lls with.**     
2eff0 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c       the same D,
2f000 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c   X, N, and E val
2f010 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  ues..**.** {H161
2f020 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
2f030 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2f040 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  (D,X,...)] inter
2f050 66 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c 0a  face shall fail.
2f060 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74  **          if t
2f070 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2f080 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20  name X is.**    
2f090 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61        longer tha
2f0a0 6e 20 32 35 35 20 62 79 74 65 73 20 65 78 63 6c  n 255 bytes excl
2f0b0 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
2f0c0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
2f0d0 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20 54 68 65  .** {H16118} The
2f0e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f0f0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2f100 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 69 6e 74 65  E,P,F,S,L)] inte
2f110 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  rface.**        
2f120 20 20 73 68 61 6c 6c 20 66 61 69 6c 20 75 6e 6c    shall fail unl
2f130 65 73 73 20 65 69 74 68 65 72 20 46 20 69 73 20  ess either F is 
2f140 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c  NULL and S and L
2f150 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72   are non-NULL or
2f160 0a 2a 2a 2a 20 20 20 20 20 20 20 20 20 46 20 69  .***         F i
2f170 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53  s non-NULL and S
2f180 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2e   and L are NULL.
2f190 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 31 7d 20  .**.** {H16121} 
2f1a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2f1b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e  ate_function(D,.
2f1c0 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  ..)] interface s
2f1d0 68 61 6c 6c 20 66 61 69 6c 73 20 77 69 74 68 20  hall fails with 
2f1e0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  an.**          e
2f1f0 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
2f200 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74 68  LITE_BUSY] if th
2f210 65 72 65 20 65 78 69 73 74 20 5b 70 72 65 70 61  ere exist [prepa
2f220 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a  red statements].
2f230 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f  **          asso
2f240 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2f250 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2f260 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
2f270 48 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71 6c  H16124} The [sql
2f280 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f290 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
2f2a0 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
2f2b0 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20   fail with.**   
2f2c0 20 20 20 20 20 20 20 61 6e 20 65 72 72 6f 72 20         an error 
2f2d0 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
2f2e0 45 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d 65  ERROR] if parame
2f2f0 74 65 72 20 4e 20 69 73 20 6c 65 73 73 0a 2a 2a  ter N is less.**
2f300 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 2d            than -
2f310 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
2f320 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  n 127..**.** {H1
2f330 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 73 20  6127} When N is 
2f340 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
2f350 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2f360 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2f370 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2f380 20 20 20 69 6e 74 65 72 66 61 63 65 20 73 68 61     interface sha
2f390 6c 6c 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  ll register call
2f3a0 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f  backs to be invo
2f3b0 6b 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  ked for the.**  
2f3c0 20 20 20 20 20 20 20 20 53 51 4c 20 66 75 6e 63          SQL func
2f3d0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
2f3e0 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 74 68   named X when th
2f3f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
2f400 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c  ments to the SQL
2f410 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
2f420 20 20 20 20 20 20 20 20 20 65 78 61 63 74 6c 79           exactly
2f430 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33   N..**.** {H1613
2f440 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c  0} When N is -1,
2f450 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2f460 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2f470 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  X,N,...)].**    
2f480 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
2f490 73 68 61 6c 6c 20 72 65 67 69 73 74 65 72 20 63  shall register c
2f4a0 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69  allbacks to be i
2f4b0 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53  nvoked for the S
2f4c0 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  QL.**          f
2f4d0 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20  unction named X 
2f4e0 77 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20  with any number 
2f4f0 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  of arguments..**
2f500 0a 2a 2a 20 7b 48 31 36 31 33 33 7d 20 57 68 65  .** {H16133} Whe
2f510 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
2f520 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f530 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a  ion(D,X,N,...)].
2f540 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63  **          spec
2f550 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ify multiple imp
2f560 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2f570 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2f580 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  n X.**          
2f590 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70  and when one imp
2f5a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20  lementation has 
2f5b0 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68  N>=0 and the oth
2f5c0 65 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a  er has N=(-1).**
2f5d0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6d            the im
2f5e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2f5f0 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 73  h a non-zero N s
2f600 68 61 6c 6c 20 62 65 20 70 72 65 66 65 72 72 65  hall be preferre
2f610 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 36  d..**.** {H16136
2f620 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  } When calls to 
2f630 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f640 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2f650 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2f660 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69     specify multi
2f670 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2f680 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2f690 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 0a  function X with.
2f6a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2f6b0 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 61  same number of a
2f6c0 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 20 77  rguments N but w
2f6d0 69 74 68 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a  ith different.**
2f6e0 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 69            encodi
2f6f0 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 68 65 20  ngs E, then the 
2f700 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2f710 68 65 72 65 20 45 20 6d 61 74 63 68 65 73 20 74  here E matches t
2f720 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  he.**          d
2f730 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
2f740 20 73 68 61 6c 6c 20 70 72 65 66 65 72 72 65 64   shall preferred
2f750 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 39 7d  ..**.** {H16139}
2f760 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61 74   For an aggregat
2f770 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  e SQL function c
2f780 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
2f790 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2f7a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f7b0 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c  n(D,X,N,E,P,0,S,
2f7c0 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c 69 7a 65  L)] the finalize
2f7d0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  r.**          fu
2f7e0 6e 63 74 69 6f 6e 20 4c 20 73 68 61 6c 6c 20 61  nction L shall a
2f7f0 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65 64  lways be invoked
2f800 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 66   exactly once if
2f810 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2f820 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 53   step function S
2f830 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   is called one o
2f840 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
2f850 0a 2a 2a 20 7b 48 31 36 31 34 32 7d 20 57 68 65  .** {H16142} Whe
2f860 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
2f870 20 65 69 74 68 65 72 20 74 68 65 20 78 46 75 6e   either the xFun
2f880 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63 74  c or xStep funct
2f890 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ion of.**       
2f8a0 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f     an applicatio
2f8b0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2f8c0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2f8d0 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 20  ate created.**  
2f8e0 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69          by [sqli
2f8f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f900 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ion()] or [sqlit
2f910 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f920 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  on16()],.**     
2f930 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 61 72       then the ar
2f940 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ray of [sqlite3_
2f950 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20 70  value] objects p
2f960 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
2f970 20 20 20 20 20 20 20 20 20 74 68 69 72 64 20 70           third p
2f980 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20 62  arameter shall b
2f990 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
2f9a0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2f9b0 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  cts..*/.int sqli
2f9c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f9d0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
2f9e0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2f9f0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2fa00 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2fa10 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2fa20 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2fa30 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2fa40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2fa50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2fa60 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2fa70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2fa80 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2fa90 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2faa0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2fab0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
2fac0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2fad0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
2fae0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2faf0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
2fb00 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2fb10 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2fb20 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2fb30 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2fb40 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2fb50 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2fb60 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2fb70 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2fb80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2fb90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2fba0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2fbb0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2fbc0 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  xt*).);../*.** C
2fbd0 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
2fbe0 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 37 7d  codings {H10267}
2fbf0 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 31 30   <S50200> <H1610
2fc00 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  0>.**.** These c
2fc10 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
2fc20 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
2fc30 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
2fc40 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
2fc50 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
2fc60 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
2fc70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2fc80 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
2fc90 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2fca0 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
2fcb0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2fcc0 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
2fcd0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
2fce0 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
2fcf0 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
2fd00 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
2fd10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2fd20 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
2fd30 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2fd40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f  reate_function o
2fd50 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
2fd60 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
2fd70 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
2fd80 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2fd90 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
2fda0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2fdb0 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
2fdc0 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
2fdd0 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
2fde0 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
2fdf0 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
2fe00 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
2fe10 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
2fe20 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
2fe30 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
2fe40 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
2fe50 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
2fe60 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
2fe70 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
2fe80 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
2fe90 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
2fea0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
2feb0 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72    To help encour
2fec0 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76  age people to av
2fed0 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  oid.** using the
2fee0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65  se functions, we
2fef0 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74   are not going t
2ff00 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20  o tell you what 
2ff10 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e  they do..*/.#ifn
2ff20 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
2ff30 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54  DEPRECATED.SQLIT
2ff40 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2ff50 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2ff60 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
2ff70 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
2ff80 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2ff90 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
2ffa0 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
2ffb0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
2ffc0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2ffd0 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
2ffe0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2fff0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
30000 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
30010 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
30020 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
30030 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
30040 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
30050 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
30060 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
30070 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
30080 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
30090 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
300a0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
300b0 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69  ,int),void*,sqli
300c0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
300d0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
300e0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
300f0 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
30100 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48 31 35  eter Values {H15
30110 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  100} <S20200>.**
30120 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
30130 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
30140 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
30150 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
30160 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
30170 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
30180 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
30190 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
301a0 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
301b0 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
301c0 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
301d0 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
301e0 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
301f0 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
30200 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
30210 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
30220 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30230 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
30240 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30250 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
30260 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
30270 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
30280 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
30290 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
302a0 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   The 4th paramet
302b0 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
302c0 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
302d0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
302e0 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
302f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30300 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
30310 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
30320 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
30330 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
30340 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
30350 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
30360 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
30370 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
30380 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
30390 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
303a0 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
303b0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
303c0 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
303d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
303e0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
303f0 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
30400 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
30410 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
30420 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30430 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
30440 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
30450 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
30460 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
30470 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
30480 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
30490 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
304a0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
304b0 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
304c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
304d0 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
304e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
304f0 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
30500 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
30510 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
30520 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
30530 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
30540 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
30550 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
30560 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
30570 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
30580 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
30590 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
305a0 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
305b0 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
305c0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
305d0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
305e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
305f0 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
30600 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
30610 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
30620 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
30630 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
30640 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
30650 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
30660 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
30670 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
30680 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
30690 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
306a0 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
306b0 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
306c0 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
306d0 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
306e0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
306f0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
30700 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
30710 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
30720 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
30730 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
30740 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
30750 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
30760 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
30770 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
30780 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
30790 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
307a0 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
307b0 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
307c0 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
307d0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
307e0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
307f0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
30800 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
30810 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
30820 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
30830 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
30840 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
30850 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
30860 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
30870 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
30880 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
30890 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
308a0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
308b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
308c0 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
308d0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
308e0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
308f0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
30900 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
30910 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
30920 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
30930 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
30940 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
30950 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
30960 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
30970 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
30980 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
30990 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
309a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
309b0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
309c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
309d0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a   parameters..**.
309e0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
309f0 2a 0a 2a 2a 20 7b 48 31 35 31 30 33 7d 20 54 68  *.** {H15103} Th
30a00 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
30a10 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72 66  _blob(V)] interf
30a20 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
30a30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
30a40 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30a50 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
30a60 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20  into a BLOB and 
30a70 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
30a80 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
30a90 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72  er to the conver
30aa0 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  ted value..**.**
30ab0 20 7b 48 31 35 31 30 36 7d 20 54 68 65 20 5b 73   {H15106} The [s
30ac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
30ad0 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  es(V)] interface
30ae0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
30af0 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
30b00 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
30b10 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28  BLOB or string (
30b20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
30b30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
30b40 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
30b50 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
30b60 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
30b70 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30b80 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
30b90 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61  l to [sqlite3_va
30ba0 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a  lue_blob(V)] or.
30bb0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
30bc0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
30bd0 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  V)]..**.** {H151
30be0 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
30bf0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 56  _value_bytes16(V
30c00 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
30c10 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
30c20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
30c30 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
30c40 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
30c50 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30c60 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
30c70 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
30c80 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
30c90 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
30ca0 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
30cb0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
30cc0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56  3_value_text16(V
30cd0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
30ce0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30cf0 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72 20  ext16be(V)], or 
30d00 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30d10 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a  ext16le(V)]..**.
30d20 2a 2a 20 7b 48 31 35 31 31 32 7d 20 54 68 65 20  ** {H15112} The 
30d30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
30d40 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 72 66  ouble(V)] interf
30d50 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
30d60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
30d70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30d80 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
30d90 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20  into a floating 
30da0 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a  point value and.
30db0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
30dc0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
30dd0 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  at value..**.** 
30de0 7b 48 31 35 31 31 35 7d 20 54 68 65 20 5b 73 71  {H15115} The [sq
30df0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
30e00 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
30e10 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
30e20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
30e30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30e40 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
30e50 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
30e60 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
30e70 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74         returns t
30e80 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73  he lower 32 bits
30e90 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
30ea0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 38 7d  ..**.** {H15118}
30eb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
30ec0 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e  lue_int64(V)] in
30ed0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
30ee0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30ef0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
30f00 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30f10 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  t V into a 64-bi
30f20 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
30f30 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
30f40 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
30f50 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
30f60 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 31 7d 20  .**.** {H15121} 
30f70 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
30f80 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e 74 65  ue_text(V)] inte
30f90 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
30fa0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
30fb0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30fc0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
30fd0 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
30fe0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
30ff0 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
31000 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
31010 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
31020 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
31030 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  15124} The [sqli
31040 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31050 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
31060 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
31070 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
31080 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31090 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
310a0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
310b0 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
310c0 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
310d0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
310e0 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
310f0 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
31100 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
31110 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
31120 2a 0a 2a 2a 20 7b 48 31 35 31 32 37 7d 20 54 68  *.** {H15127} Th
31130 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
31140 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20 69 6e  _text16be(V)] in
31150 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
31160 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
31170 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
31180 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
31190 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  t V into a zero-
311a0 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74  terminated 2-byt
311b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  e.**          al
311c0 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62 69 67  igned UTF-16 big
311d0 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
311e0 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
311f0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
31200 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
31210 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 30 7d 20  .**.** {H15130} 
31220 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
31230 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 20  ue_text16le(V)] 
31240 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
31250 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
31260 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
31270 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31280 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72  ect V into a zer
31290 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62  o-terminated 2-b
312a0 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  yte.**          
312b0 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6c  aligned UTF-16 l
312c0 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20  ittle-endian.** 
312d0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
312e0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
312f0 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
31300 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
31310 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  133} The [sqlite
31320 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 29 5d  3_value_type(V)]
31330 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
31340 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ns.**          o
31350 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55  ne of [SQLITE_NU
31360 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54  LL], [SQLITE_INT
31370 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
31380 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  LOAT],.**       
31390 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d     [SQLITE_TEXT]
313a0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  , or [SQLITE_BLO
313b0 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
313c0 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
313d0 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    the [sqlite3_v
313e0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a  alue] object V..
313f0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 36 7d 20 54  **.** {H15136} T
31400 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
31410 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 56  e_numeric_type(V
31420 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
31430 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  verts.**        
31440 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64    the [protected
31450 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
31460 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 65 69  object V into ei
31470 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65 72 20  ther an integer 
31480 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  or.**          a
31490 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
314a0 76 61 6c 75 65 20 69 66 20 69 74 20 63 61 6e 20  value if it can 
314b0 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f  do so without lo
314c0 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ss of.**        
314d0 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61    information, a
314e0 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f  nd returns one o
314f0 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c  f [SQLITE_NULL],
31500 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
31510 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b  LITE_INTEGER], [
31520 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
31530 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72  SQLITE_TEXT], or
31540 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
31550 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70  LITE_BLOB] as ap
31560 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68  propriate for th
31570 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
31580 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
31590 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
315a0 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e 76 65   after the conve
315b0 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a  rsion attempt..*
315c0 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
315d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
315e0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
315f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
31600 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
31610 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
31620 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
31630 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
31640 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
31650 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
31660 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
31670 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
31680 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
31690 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
316a0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
316b0 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
316c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
316d0 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
316e0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
316f0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
31700 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
31710 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
31720 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
31730 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
31740 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
31750 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
31760 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
31770 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31780 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
31790 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
317a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
317b0 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
317c0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
317d0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
317e0 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
317f0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
31800 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
31810 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
31820 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36 32  on Context {H162
31830 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  10} <S20200>.**.
31840 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** The implement
31850 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61  ation of aggrega
31860 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
31870 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e   use this routin
31880 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a  e to allocate.**
31890 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72   a structure for
318a0 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
318b0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tate..**.** The 
318c0 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
318d0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
318e0 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69  _context() routi
318f0 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  ne is called for
31900 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72   a.** particular
31910 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69   aggregate, SQLi
31920 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79  te allocates nBy
31930 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  tes of memory, z
31940 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a 2a  eroes out that.*
31950 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  * memory, and re
31960 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
31970 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64  to it. On second
31980 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
31990 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
319a0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
319b0 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
319c0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
319d0 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a  unction index,.*
319e0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
319f0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54  r is returned. T
31a00 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
31a10 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  n of the aggrega
31a20 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68  te can use.** th
31a30 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65  e returned buffe
31a40 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20  r to accumulate 
31a50 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  data..**.** SQLi
31a60 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
31a70 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63   frees the alloc
31a80 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65 6e  ated buffer when
31a90 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
31aa0 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  * query conclude
31ab0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
31ac0 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  st parameter sho
31ad0 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66  uld be a copy of
31ae0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
31af0 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
31b00 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
31b10 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
31b20 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
31b30 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
31b40 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
31b50 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
31b60 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a  egate function..
31b70 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
31b80 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
31b90 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
31ba0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
31bb0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
31bc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
31bd0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
31be0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
31bf0 2a 20 7b 48 31 36 32 31 31 7d 20 54 68 65 20 66  * {H16211} The f
31c00 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  irst invocation 
31c10 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  of [sqlite3_aggr
31c20 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
31c30 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  N)] for.**      
31c40 20 20 20 20 61 20 70 61 72 74 69 63 75 6c 61 72      a particular
31c50 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e 20   instance of an 
31c60 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
31c70 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74 69 63  on (for a partic
31c80 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ular.**         
31c90 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61 75 73   context C) caus
31ca0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61 6c 6c  es SQLite to all
31cb0 6f 63 61 74 65 20 4e 20 62 79 74 65 73 20 6f 66  ocate N bytes of
31cc0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20   memory,.**     
31cd0 20 20 20 20 20 7a 65 72 6f 20 74 68 61 74 20 6d       zero that m
31ce0 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
31cf0 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  n a pointer to t
31d00 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d  he allocated mem
31d10 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  ory..**.** {H162
31d20 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20  13} If a memory 
31d30 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
31d40 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 0a 2a   occurs during.*
31d50 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
31d60 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
31d70 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e  ntext(C,N)] then
31d80 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   the function re
31d90 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b  turns 0..**.** {
31da0 48 31 36 32 31 35 7d 20 53 65 63 6f 6e 64 20 61  H16215} Second a
31db0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  nd subsequent in
31dc0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20  vocations of.** 
31dd0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
31de0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31df0 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68  ext(C,N)] for th
31e00 65 20 73 61 6d 65 20 63 6f 6e 74 65 78 74 20 70  e same context p
31e10 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20 20  ointer C.**     
31e20 20 20 20 20 20 69 67 6e 6f 72 65 20 74 68 65 20       ignore the 
31e30 4e 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  N parameter and 
31e40 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
31e50 20 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   to the same.** 
31e60 20 20 20 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f           block o
31e70 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  f memory returne
31e80 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 69  d by the first i
31e90 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
31ea0 20 7b 48 31 36 32 31 37 7d 20 54 68 65 20 6d 65   {H16217} The me
31eb0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
31ec0 79 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  y [sqlite3_aggre
31ed0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
31ee0 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
31ef0 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20    automatically 
31f00 66 72 65 65 64 20 6f 6e 20 74 68 65 20 6e 65 78  freed on the nex
31f10 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
31f20 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20  e3_reset()].**  
31f30 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
31f40 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
31f50 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
31f60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e  d statement] con
31f70 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20  taining.**      
31f80 20 20 20 20 74 68 65 20 61 67 67 72 65 67 61 74      the aggregat
31f90 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63  e function assoc
31fa0 69 61 74 65 64 20 77 69 74 68 20 63 6f 6e 74 65  iated with conte
31fb0 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  xt C..*/.void *s
31fc0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31fd0 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
31fe0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
31ff0 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
32000 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
32010 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
32020 20 7b 48 31 36 32 34 30 7d 20 3c 53 32 30 32 30   {H16240} <S2020
32030 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
32040 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
32050 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
32060 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
32070 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
32080 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
32090 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
320a0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
320b0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
320c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
320d0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
320e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
320f0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
32100 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
32110 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
32120 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
32130 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
32140 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ion. {END}.**.**
32150 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
32160 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
32170 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
32180 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
32190 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
321a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
321b0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
321c0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
321d0 2a 2a 20 7b 48 31 36 32 34 33 7d 20 54 68 65 20  ** {H16243} The 
321e0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
321f0 74 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ta(C)] interface
32200 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
32210 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
32220 20 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f     P pointer fro
32230 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  m the [sqlite3_c
32240 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
32250 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
32260 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
32270 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32280 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e  function16(D,X,N
32290 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c  ,E,P,F,S,L)] cal
322a0 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  l that.**       
322b0 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68     registered th
322c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
322d0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b  ssociated with [
322e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
322f0 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c   C..*/.void *sql
32300 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
32310 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32320 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32330 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
32340 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
32350 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c 53  ions {H16250} <S
32360 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a  60600><S20200>.*
32370 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
32380 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
32390 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
323a0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
323b0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
323c0 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
323d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
323e0 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
323f0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
32400 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32410 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
32420 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32430 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
32440 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
32450 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
32460 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
32470 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
32480 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ion..**.** INVAR
32490 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
324a0 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  6253} The [sqlit
324b0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
324c0 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72 66 61  ndle(C)] interfa
324d0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
324e0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  y of the.**     
324f0 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72 20 66       D pointer f
32500 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
32510 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32520 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
32530 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
32540 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
32550 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58  e_function16(D,X
32560 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63  ,N,E,P,F,S,L)] c
32570 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20  all that.**     
32580 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
32590 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
325a0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
325b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
325c0 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  t] C..*/.sqlite3
325d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
325e0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
325f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
32600 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32610 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
32620 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 30 7d  ry Data {H16270}
32630 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
32640 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
32650 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
32660 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
32670 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
32680 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
32690 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
326a0 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
326b0 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
326c0 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
326d0 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
326e0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
326f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
32700 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
32710 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
32720 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
32730 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
32740 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
32750 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
32760 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
32770 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
32780 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
32790 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
327a0 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
327b0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
327c0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
327d0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
327e0 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
327f0 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
32800 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
32810 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
32820 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
32830 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
32840 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
32850 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
32860 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
32870 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
32880 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
32890 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
328a0 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
328b0 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
328c0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
328d0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
328e0 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
328f0 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
32900 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  on..**.** The sq
32910 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
32920 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
32930 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
32940 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
32950 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
32960 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
32970 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
32980 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
32990 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
329a0 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
329b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
329c0 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65  nction. If no me
329d0 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
329e0 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74  ever.** been set
329f0 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67   for the Nth arg
32a00 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
32a10 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
32a20 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
32a30 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
32a40 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64  eter has changed
32a50 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
32a60 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a  data was set,.**
32a70 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
32a80 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75  t_auxdata() retu
32a90 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
32aa0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
32ab0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
32ac0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  a() interface sa
32ad0 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61  ves the metadata
32ae0 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
32af0 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  y its 3rd parame
32b00 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64  ter as the metad
32b10 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
32b20 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
32b30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
32b40 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
32b50 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a  .  Subsequent.**
32b60 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
32b70 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
32b80 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69  might return thi
32b90 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61  s data, if it ha
32ba0 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65  s.** not been de
32bb0 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69  stroyed..** If i
32bc0 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  t is not NULL, S
32bd0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
32be0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
32bf0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76  .** function giv
32c00 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61  en by the 4th pa
32c10 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
32c20 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
32c30 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64   on.** the metad
32c40 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72  ata when the cor
32c50 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
32c60 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
32c70 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  anges.** or when
32c80 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
32c90 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68  nt completes, wh
32ca0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
32cb0 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  rst..**.** SQLit
32cc0 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c  e is free to cal
32cd0 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  l the destructor
32ce0 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61   and drop metada
32cf0 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72  ta on any.** par
32d00 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
32d10 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
32d20 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75  me.  The only gu
32d30 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a  arantee is that.
32d40 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ** the destructo
32d50 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
32d60 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
32d70 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e  data is dropped.
32d80 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69  .**.** In practi
32d90 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
32da0 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
32db0 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
32dc0 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
32dd0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
32de0 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
32df0 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
32e00 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
32e10 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76  values and SQL v
32e20 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  ariables..**.** 
32e30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
32e40 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
32e50 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
32e60 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
32e70 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
32e80 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
32e90 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
32ea0 0a 2a 2a 20 7b 48 31 36 32 37 32 7d 20 54 68 65  .** {H16272} The
32eb0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
32ec0 78 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65  xdata(C,N)] inte
32ed0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
32ee0 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
32ef0 20 20 20 20 74 6f 20 6d 65 74 61 64 61 74 61 20      to metadata 
32f00 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
32f10 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65  the Nth paramete
32f20 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  r of the SQL fun
32f30 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
32f40 20 20 77 68 6f 73 65 20 63 6f 6e 74 65 78 74 20    whose context 
32f50 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66  is C, or NULL if
32f60 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74   there is no met
32f70 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
32f80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
32f90 68 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  h that parameter
32fa0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 34 7d  ..**.** {H16274}
32fb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
32fc0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
32fd0 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 73  D)] interface as
32fe0 73 69 67 6e 73 20 61 20 6d 65 74 61 64 61 74 61  signs a metadata
32ff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
33000 6e 74 65 72 20 50 20 74 6f 20 74 68 65 20 4e 74  nter P to the Nt
33010 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  h parameter of t
33020 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
33030 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a  with context C..
33040 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 36 7d 20 53  **.** {H16276} S
33050 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
33060 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
33070 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65   D with a single
33080 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
33090 20 20 20 20 20 20 77 68 69 63 68 20 69 73 20 74        which is t
330a0 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69 6e  he metadata poin
330b0 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20  ter P following 
330c0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
330d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
330e0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
330f0 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74 65  ,D)] when SQLite
33100 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a   ceases to hold.
33110 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
33120 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  metadata..**.** 
33130 7b 48 31 36 32 37 37 7d 20 53 51 4c 69 74 65 20  {H16277} SQLite 
33140 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d  ceases to hold m
33150 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20 53  etadata for an S
33160 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  QL function para
33170 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
33180 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75 65    when the value
33190 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65 74   of that paramet
331a0 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  er changes..**.*
331b0 2a 20 7b 48 31 36 32 37 38 7d 20 57 68 65 6e 20  * {H16278} When 
331c0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
331d0 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69  data(C,N,P,D)] i
331e0 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64  s invoked, the d
331f0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20  estructor.**    
33200 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64 20        is called 
33210 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d 65  for any prior me
33220 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
33230 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  d with the same 
33240 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
33250 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20 61       context C a
33260 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a  nd parameter N..
33270 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 39 7d 20 53  **.** {H16279} S
33280 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20  QLite will call 
33290 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20  destructors for 
332a0 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74 20  any metadata it 
332b0 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20  is holding.**   
332c0 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 72 74         in a part
332d0 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65 64  icular [prepared
332e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77 68   statement] S wh
332f0 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  en either.**    
33300 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
33310 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c  eset(S)] or [sql
33320 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
33330 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a  ] is called..*/.
33340 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
33350 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
33360 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
33370 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
33380 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
33390 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
333a0 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
333b0 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
333c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
333d0 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
333e0 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
333f0 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20  ructor Behavior 
33400 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31 30 30  {H10280} <S30100
33410 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  >.**.** These ar
33420 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
33430 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
33440 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
33450 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
33460 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
33470 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
33480 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
33490 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65  blob()].  If the
334a0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
334b0 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
334c0 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
334d0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
334e0 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
334f0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
33500 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
33510 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
33520 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
33530 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c  yed.  The.** SQL
33540 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
33550 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
33560 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
33570 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
33580 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
33590 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
335a0 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
335b0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
335c0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
335d0 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
335e0 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
335f0 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
33600 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
33610 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
33620 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
33630 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
33640 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
33650 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
33660 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
33670 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
33680 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
33690 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
336a0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
336b0 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
336c0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
336d0 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
336e0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
336f0 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
33700 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
33710 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
33720 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34  L Function {H164
33730 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  00} <S20200>.**.
33740 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
33750 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
33760 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
33770 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
33780 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
33790 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
337a0 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
337b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
337c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
337d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
337e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
337f0 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
33800 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
33810 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
33820 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
33830 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
33840 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
33850 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
33860 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
33870 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
33880 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
33890 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
338a0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
338b0 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
338c0 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
338d0 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
338e0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
338f0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  n..**.** The sql
33900 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
33910 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
33920 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
33930 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
33940 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33950 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
33960 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
33970 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
33980 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
33990 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
339a0 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
339b0 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
339c0 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
339d0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
339e0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
339f0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
33a00 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
33a10 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
33a20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33a30 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
33a40 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
33a50 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
33a60 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
33a70 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
33a80 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
33a90 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
33aa0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  meter..**.** The
33ab0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33ac0 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
33ad0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
33ae0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
33af0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33b00 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
33b10 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
33b20 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
33b30 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
33b40 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
33b50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33b60 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
33b70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33b80 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
33b90 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
33ba0 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
33bb0 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
33bc0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
33bd0 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
33be0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
33bf0 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
33c00 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
33c10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33c20 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
33c30 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33c40 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
33c50 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
33c60 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e  sage.  SQLite in
33c70 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
33c80 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
33c90 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
33ca0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
33cb0 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74   as UTF-8. SQLit
33cc0 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
33cd0 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
33ce0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33cf0 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
33d00 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
33d10 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20  byte order.  If 
33d20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
33d30 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
33d40 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
33d50 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
33d60 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
33d70 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
33d80 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
33d90 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
33da0 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
33db0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
33dc0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
33dd0 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72 64  .** If the third
33de0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
33df0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33e00 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
33e10 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
33e20 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
33e30 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
33e40 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
33e50 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
33e60 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
33e70 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
33e80 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
33e90 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71  ssage..** The sq
33ea0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33eb0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
33ec0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33ed0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
33ee0 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
33ef0 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
33f00 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
33f10 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
33f20 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
33f30 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
33f40 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
33f50 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
33f60 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
33f70 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
33f80 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  arm..** The sqli
33f90 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33fa0 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
33fb0 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
33fc0 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
33fd0 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
33fe0 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
33ff0 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
34000 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ion.  By default
34010 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
34020 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
34030 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75 65  ROR.  A subseque
34040 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
34050 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
34060 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
34070 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34080 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f   resets the erro
34090 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45  r code to SQLITE
340a0 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68  _ERROR..**.** Th
340b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
340c0 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
340d0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
340e0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
340f0 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
34100 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
34110 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f  or BLOB is to lo
34120 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
34130 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
34140 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28  e3_result_nomem(
34150 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
34160 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
34170 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
34180 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
34190 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
341a0 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
341b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
341c0 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
341d0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
341e0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
341f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34200 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34210 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
34220 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
34230 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
34240 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
34250 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ent..** The sqli
34260 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
34270 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
34280 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
34290 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
342a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
342b0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
342c0 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
342d0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
342e0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
342f0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
34300 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
34310 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
34320 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
34330 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
34340 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
34350 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34360 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
34370 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
34380 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
34390 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
343a0 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
343b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
343c0 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
343d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
343e0 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
343f0 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
34400 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
34410 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34420 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
34430 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
34440 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
34450 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
34460 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
34470 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
34480 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
34490 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
344a0 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
344b0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51  pectively..** SQ
344c0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
344d0 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
344e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
344f0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
34500 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
34510 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34520 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34530 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
34540 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
34550 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34560 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34570 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
34580 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
34590 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
345a0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
345b0 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
345c0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
345d0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66  character..** If
345e0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
345f0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
34600 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
34610 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
34620 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
34630 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
34640 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
34650 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
34660 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
34670 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
34680 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
34690 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
346a0 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
346b0 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  n result..** If 
346c0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
346d0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
346e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
346f0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
34700 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34710 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
34720 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
34730 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
34740 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
34750 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
34760 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
34770 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
34780 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
34790 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
347a0 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34  ult..** If the 4
347b0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
347c0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
347d0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
347e0 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ces or.** sqlite
347f0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
34800 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
34810 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
34820 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
34830 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
34840 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
34850 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
34860 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
34870 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
34880 70 79 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c  py the it or cal
34890 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 77  l a destructor w
348a0 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
348b0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
348c0 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
348d0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
348e0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
348f0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
34900 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
34910 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
34920 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
34930 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
34940 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
34950 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
34960 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
34970 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
34980 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
34990 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
349a0 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
349b0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
349c0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
349d0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
349e0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
349f0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
34a00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34a10 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
34a20 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
34a30 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
34a40 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34a50 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
34a60 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
34a70 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  r.  The.** sqlit
34a80 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
34a90 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
34aa0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
34ab0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
34ac0 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
34ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
34ae0 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
34af0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
34b00 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
34b10 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
34b20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34b30 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
34b40 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
34b50 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  A [protected sql
34b60 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34b70 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65  ct may always be
34b80 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a   used where an.*
34b90 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
34ba0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34bb0 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64  ject is required
34bc0 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b  , so either.** k
34bd0 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ind of [sqlite3_
34be0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61  value] object ca
34bf0 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74  n be used with t
34c00 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
34c10 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f  *.** If these ro
34c20 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
34c30 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68  d from within th
34c40 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  e different thre
34c50 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f  ad.** than the o
34c60 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ne containing th
34c70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34c80 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
34c90 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20  hat received.** 
34ca0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
34cb0 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74  text] pointer, t
34cc0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
34cd0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
34ce0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
34cf0 2a 20 7b 48 31 36 34 30 33 7d 20 54 68 65 20 64  * {H16403} The d
34d00 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20 76 61  efault return va
34d10 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c  lue from any SQL
34d20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c   function is NUL
34d30 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 36  L..**.** {H16406
34d40 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
34d50 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
34d60 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
34d70 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
34d80 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
34d90 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
34da0 43 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 74  C to be a BLOB t
34db0 68 61 74 20 69 73 20 4e 20 62 79 74 65 73 0a 2a  hat is N bytes.*
34dc0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 6c 65  *          in le
34dd0 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20 63 6f  ngth and with co
34de0 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f  ntent pointed to
34df0 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   by V..**.** {H1
34e00 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  6409} The [sqlit
34e10 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
34e20 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
34e30 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
34e40 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
34e50 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
34e60 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 66 6c  n C to be the fl
34e70 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
34e80 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ue V..**.** {H16
34e90 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  412} The [sqlite
34ea0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 43  3_result_error(C
34eb0 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,V,N)] interface
34ec0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
34ed0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
34ee0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
34ef0 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
34f00 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
34f10 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
34f20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
34f30 5d 20 61 6e 64 20 61 20 55 54 46 2d 38 20 65 72  ] and a UTF-8 er
34f40 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f 70 69  ror message copi
34f50 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20  ed from V up to 
34f60 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
34f70 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65 20  first zero byte 
34f80 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
34f90 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69   are read if N i
34fa0 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a  s positive..**.*
34fb0 2a 20 7b 48 31 36 34 31 35 7d 20 54 68 65 20 5b  * {H16415} The [
34fc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34fd0 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69  rror16(C,V,N)] i
34fe0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
34ff0 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
35000 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
35010 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
35020 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77  e an exception w
35030 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  ith error code.*
35040 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
35050 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20  TE_ERROR] and a 
35060 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
35070 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20 6d  te order error m
35080 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20  essage.**       
35090 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56     copied from V
350a0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
350b0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
350c0 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65   or until N byte
350d0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  s.**          ar
350e0 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70  e read if N is p
350f0 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  ositive..**.** {
35100 48 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71 6c  H16418} The [sql
35110 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35120 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74  r_toobig(C)] int
35130 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
35140 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
35150 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74        value of t
35160 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  he function C to
35170 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
35180 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
35190 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
351a0 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64  LITE_TOOBIG] and
351b0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
351c0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
351d0 2a 0a 2a 2a 20 7b 48 31 36 34 32 31 7d 20 54 68  *.** {H16421} Th
351e0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
351f0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29  t_error_nomem(C)
35200 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
35210 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
35220 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
35230 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
35240 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
35250 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
35260 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
35270 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
35280 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69   and an appropri
35290 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ate error messag
352a0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 34  e..**.** {H16424
352b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
352c0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
352d0 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,E)] interface
352e0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
352f0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
35300 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
35310 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
35320 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
35330 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a  error code E..**
35340 20 20 20 20 20 20 20 20 20 20 54 68 65 20 65 72            The er
35350 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
35360 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
35370 2a 0a 2a 2a 20 7b 48 31 36 34 32 37 7d 20 54 68  *.** {H16427} Th
35380 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
35390 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65  t_int(C,V)] inte
353a0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
353b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
353c0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
353d0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
353e0 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  he 32-bit intege
353f0 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  r value V..**.**
35400 20 7b 48 31 36 34 33 30 7d 20 54 68 65 20 5b 73   {H16430} The [s
35410 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
35420 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  t64(C,V)] interf
35430 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
35440 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
35450 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
35460 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
35470 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
35480 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
35490 48 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71 6c  H16433} The [sql
354a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
354b0 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
354c0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
354d0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
354e0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
354f0 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  C to be NULL..**
35500 0a 2a 2a 20 7b 48 31 36 34 33 36 7d 20 54 68 65  .** {H16436} The
35510 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35520 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20  _text(C,V,N,D)] 
35530 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
35540 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
35550 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
35560 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
35570 62 65 20 74 68 65 20 55 54 46 2d 38 20 73 74 72  be the UTF-8 str
35580 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
35590 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
355a0 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e  t zero if N is n
355b0 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
355c0 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74      or the first
355d0 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
355e0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
355f0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33  ve..**.** {H1643
35600 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
35610 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
35620 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
35630 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
35640 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
35650 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
35660 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
35670 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
35680 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
35690 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
356a0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
356b0 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
356c0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
356d0 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
356e0 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
356f0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
35700 2a 0a 2a 2a 20 7b 48 31 36 34 34 32 7d 20 54 68  *.** {H16442} Th
35710 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
35720 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
35730 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
35740 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
35750 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
35760 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
35770 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
35780 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a  16 big-endian.**
35790 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
357a0 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
357b0 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20  st zero if N is 
357c0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
357d0 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73       or the firs
357e0 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56 20 69  t N bytes or V i
357f0 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
35800 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ive..**.** {H164
35810 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  45} The [sqlite3
35820 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
35830 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
35840 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
35850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
35860 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
35870 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
35880 65 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  e UTF-16 little-
35890 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
358a0 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74     string V up t
358b0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
358c0 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
358d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  e.**          or
358e0 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74   the first N byt
358f0 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20  es of V if N is 
35900 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
35910 0a 2a 2a 20 7b 48 31 36 34 34 38 7d 20 54 68 65  .** {H16448} The
35920 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35930 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74  _value(C,V)] int
35940 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
35950 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
35960 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
35970 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
35980 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
35990 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
359a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65  **          obje
359b0 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ct V..**.** {H16
359c0 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  451} The [sqlite
359d0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
359e0 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  b(C,N)] interfac
359f0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
35a00 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
35a10 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
35a20 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d  on C to be an N-
35a30 62 79 74 65 20 42 4c 4f 42 20 6f 66 20 61 6c 6c  byte BLOB of all
35a40 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48   zeros..**.** {H
35a50 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71 6c 69  16454} The [sqli
35a60 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35a70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
35a80 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35a90 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
35aa0 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 20 61  nterfaces make a
35ab0 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72 20 65   copy of their e
35ac0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
35ad0 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20  ings before.**  
35ae0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 69 6e          returnin
35af0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 37  g..**.** {H16457
35b00 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
35b10 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
35b20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
35b30 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
35b40 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
35b50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35b60 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
35b70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35b80 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
35b90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
35ba0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35bb0 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
35bc0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
35bd0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35be0 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
35bf0 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61  )] is the consta
35c00 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  nt [SQLITE_STATI
35c10 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  C].**          t
35c20 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63 74 6f  hen no destructo
35c30 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c 65 64  r is ever called
35c40 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65 72 20   on the pointer 
35c50 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20  V and SQLite.** 
35c60 20 20 20 20 20 20 20 20 20 61 73 73 75 6d 65 73           assumes
35c70 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d 75 74   that V is immut
35c80 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  able..**.** {H16
35c90 34 36 30 7d 20 49 66 20 74 68 65 20 44 20 64 65  460} If the D de
35ca0 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
35cb0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
35cc0 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
35cd0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
35ce0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
35cf0 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
35d00 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
35d10 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
35d20 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
35d30 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35d40 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
35d50 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
35d60 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
35d70 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
35d80 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e  N,D)] is the con
35d90 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  stant.**        
35da0 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49    [SQLITE_TRANSI
35db0 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20 69 6e  ENT] then the in
35dc0 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73 20 61  terfaces makes a
35dd0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
35de0 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 6e 74           content
35df0 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61 69 6e   of V and retain
35e00 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a  s the copy..**.*
35e10 2a 20 7b 48 31 36 34 36 33 7d 20 49 66 20 74 68  * {H16463} If th
35e20 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70  e D destructor p
35e30 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
35e40 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
35e50 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
35e60 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
35e70 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
35e80 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ,N,D)], [sqlite3
35e90 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
35ea0 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
35eb0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
35ec0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43  esult_text16be(C
35ed0 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,N,D)], or.** 
35ee0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
35ef0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
35f00 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73  e(C,V,N,D)] is s
35f10 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65 72 20  ome value other 
35f20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
35f30 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
35f40 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 20 61  SQLITE_STATIC] a
35f50 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  nd [SQLITE_TRANS
35f60 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a 20 20 20  IENT] then.**   
35f70 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 77 69         SQLite wi
35f80 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
35f90 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20  structor D with 
35fa0 56 20 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72  V as its only ar
35fb0 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  gument.**       
35fc0 20 20 20 77 68 65 6e 20 69 74 20 68 61 73 20 66     when it has f
35fd0 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
35fe0 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69   V value..*/.voi
35ff0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36000 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
36010 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
36020 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
36030 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
36040 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
36050 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
36060 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
36070 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36080 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74  sult_error(sqlit
36090 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
360a0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a  st char*, int);.
360b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
360c0 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
360d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
360e0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
360f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36100 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
36110 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
36120 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
36130 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
36140 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e  omem(sqlite3_con
36150 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
36160 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36170 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63  r_code(sqlite3_c
36180 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
36190 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
361a0 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63  lt_int(sqlite3_c
361b0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
361c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
361d0 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
361e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
361f0 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  e3_int64);.void 
36200 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
36210 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
36220 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
36230 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
36240 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36250 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
36260 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
36270 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
36280 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
36290 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
362a0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
362b0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
362c0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
362d0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
362e0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
362f0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
36300 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
36310 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
36320 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
36330 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
36340 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
36350 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
36360 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
36370 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
36380 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36390 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
363a0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
363b0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
363c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
363d0 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  *, int n);../*.*
363e0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69  * CAPI3REF: Defi
363f0 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67  ne New Collating
36400 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31 36 36   Sequences {H166
36410 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a  00} <S20300>.**.
36420 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
36430 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ns are used to a
36440 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  dd new collation
36450 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68   sequences to th
36460 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
36470 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
36480 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
36490 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
364a0 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
364b0 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  e new collation 
364c0 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63  sequence is spec
364d0 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38  ified as a UTF-8
364e0 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
364f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36500 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
36510 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36520 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
36530 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
36540 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ng for sqlite3_c
36550 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
36560 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65  6(). In all case
36570 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73  s.** the name is
36580 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
36590 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
365a0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
365b0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
365c0 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  t may be one of 
365d0 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
365e0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
365f0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
36600 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
36610 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6BE], indicating
36620 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73   that the user-s
36630 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69  upplied.** routi
36640 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65  ne expects to be
36650 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73   passed pointers
36660 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f   to strings enco
36670 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c  ded using UTF-8,
36680 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
36690 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e-endian, or UTF
366a0 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20  -16 big-endian, 
366b0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68  respectively. Th
366c0 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d  e.** third argum
366d0 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62  ent might also b
366e0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
366f0 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69  ALIGNED] to indi
36700 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  cate that.** the
36710 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
36720 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d   pointers to 16-
36730 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64  bit word aligned
36740 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55   strings.** of U
36750 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
36760 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 6f  ive byte order o
36770 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75  f the host compu
36780 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  ter..**.** A poi
36790 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72  nter to the user
367a0 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e   supplied routin
367b0 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  e must be passed
367c0 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a   as the fifth.**
367d0 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 69   argument.  If i
367e0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20  t is NULL, this 
367f0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64  is the same as d
36800 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c  eleting the coll
36810 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
36820 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74  e (so that SQLit
36830 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74  e cannot call it
36840 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61   anymore)..** Ea
36850 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c  ch time the appl
36860 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64  ication supplied
36870 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
36880 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
36890 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72  ed.** as its fir
368a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 63  st parameter a c
368b0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
368c0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
368d0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
368e0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  * to sqlite3_cre
368f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
36900 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
36910 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
36920 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  .**.** The remai
36930 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74  ning arguments t
36940 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
36950 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  n-supplied routi
36960 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e  ne are two strin
36970 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72  gs,.** each repr
36980 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65  esented by a (le
36990 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72  ngth, data) pair
369a0 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20   and encoded in 
369b0 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  the encoding.** 
369c0 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20  that was passed 
369d0 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  as the third arg
369e0 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63  ument when the c
369f0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
36a00 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65  e was.** registe
36a10 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20  red. {END}  The 
36a20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
36a30 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f  ned collation ro
36a40 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20  utine should.** 
36a50 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c  return negative,
36a60 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76   zero or positiv
36a70 65 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  e if the first s
36a80 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
36a90 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c  an,.** equal to,
36aa0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
36ab0 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69   the second stri
36ac0 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47  ng. i.e. (STRING
36ad0 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a  1 - STRING2)..**
36ae0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
36af0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36b00 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
36b10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36b20 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65  collation().** e
36b30 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74 61  xcept that it ta
36b40 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67  kes an extra arg
36b50 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
36b60 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a   destructor for.
36b70 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ** the collation
36b80 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
36b90 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e  r is called when
36ba0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
36bb0 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61  s.** destroyed a
36bc0 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63  nd is passed a c
36bd0 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74  opy of the fourt
36be0 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64  h parameter void
36bf0 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20  * pointer.** of 
36c00 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
36c10 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
36c20 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73  )..** Collations
36c30 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
36c40 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
36c50 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
36c60 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
36c70 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
36c80 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
36c90 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62   when the [datab
36ca0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36cb0 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69  is closed.** usi
36cc0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
36cd0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  e()]..**.** INVA
36ce0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
36cf0 31 36 36 30 33 7d 20 41 20 73 75 63 63 65 73 73  16603} A success
36d00 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a  ful call to the.
36d10 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
36d20 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36d30 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
36d40 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,D)] interface
36d50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
36d60 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20  isters function 
36d70 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69  F as the compari
36d80 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65  son function use
36d90 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
36da0 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61   implement colla
36db0 74 69 6f 6e 20 58 20 6f 6e 20 74 68 65 20 5b 64  tion X on the [d
36dc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36dd0 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20  on] B for.**    
36de0 20 20 20 20 20 20 64 61 74 61 62 61 73 65 73 20        databases 
36df0 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20  having encoding 
36e00 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 34  E..**.** {H16604
36e10 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72 73 74  } SQLite underst
36e20 61 6e 64 73 20 74 68 65 20 58 20 70 61 72 61 6d  ands the X param
36e30 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
36e40 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
36e50 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
36e60 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61  (B,X,E,P,F,D)] a
36e70 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
36e80 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
36e90 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 20  UTF-8 string in 
36ea0 77 68 69 63 68 20 63 61 73 65 20 69 73 20 69 67  which case is ig
36eb0 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49 49 20  nored for ASCII 
36ec0 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 0a 2a  characters and.*
36ed0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 73 69  *          is si
36ee0 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f  gnificant for no
36ef0 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63 74 65  n-ASCII characte
36f00 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30  rs..**.** {H1660
36f10 36 7d 20 53 75 63 63 65 73 73 69 76 65 20 63 61  6} Successive ca
36f20 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
36f30 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36f40 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
36f50 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
36f60 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  th the same valu
36f70 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64  es for B, X, and
36f80 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70 72 69   E, override pri
36f90 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  or values.**    
36fa0 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c 20 61        of P, F, a
36fb0 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  nd D..**.** {H16
36fc0 36 30 39 7d 20 49 66 20 74 68 65 20 64 65 73 74  609} If the dest
36fd0 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c  ructor D in [sql
36fe0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36ff0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
37000 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
37010 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74     is not NULL t
37020 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65 64  hen it is called
37030 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
37040 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   when the.**    
37050 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
37060 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
37070 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ped by SQLite..*
37080 2a 0a 2a 2a 20 7b 48 31 36 36 31 32 7d 20 41 20  *.** {H16612} A 
37090 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
370a0 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68  on is dropped wh
370b0 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f 61  en it is overloa
370c0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  ded..**.** {H166
370d0 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  15} A collating 
370e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
370f0 70 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74  ped when the dat
37100 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37110 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
37120 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
37130 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
37140 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 38 7d 20 54  **.** {H16618} T
37150 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20  he pointer P in 
37160 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37170 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
37180 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20  ,E,P,F,D)].**   
37190 20 20 20 20 20 20 20 69 73 20 70 61 73 73 65 64         is passed
371a0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
371b0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
371c0 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  to the compariso
371d0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  n.**          fu
371e0 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
371f0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
37200 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a  cations of F..**
37210 0a 2a 2a 20 7b 48 31 36 36 32 31 7d 20 41 20 63  .** {H16621} A c
37220 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37230 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
37240 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20  (B,X,E,P,F)] is 
37250 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20  exactly.**      
37260 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20      the same as 
37270 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
37280 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37290 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a  ion_v2()] with.*
372a0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
372b0 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  ame parameters a
372c0 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72 75  nd a NULL destru
372d0 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ctor..**.** {H16
372e0 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61  624} Following a
372f0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
37300 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
37310 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20  X,E,P,F,D)],.** 
37320 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20           SQLite 
37330 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72 69  uses the compari
37340 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20 66  son function F f
37350 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70  or all text comp
37360 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
37370 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e     operations on
37380 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
37390 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20  onnection] B on 
373a0 74 65 78 74 20 76 61 6c 75 65 73 20 74 68 61 74  text values that
373b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65  .**          use
373c0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73   the collating s
373d0 65 71 75 65 6e 63 65 20 6e 61 6d 65 64 20 58 2e  equence named X.
373e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 37 7d 20  .**.** {H16627} 
373f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
37400 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
37410 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b  B,X,E,P,F)] work
37420 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  s the same.**   
37430 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69 74         as [sqlit
37440 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37450 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20  ion(B,X,E,P,F)] 
37460 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 0a  except that the.
37470 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
37480 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20  ation name X is 
37490 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20 55 54  understood as UT
374a0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62  F-16 in native b
374b0 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
374c0 20 20 20 20 20 20 69 6e 73 74 65 61 64 20 6f 66        instead of
374d0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
374e0 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74  16630} When mult
374f0 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20  iple comparison 
37500 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 76  functions are av
37510 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68 65 20  ailable for the 
37520 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
37530 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
37540 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f  nce, SQLite choo
37550 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68 6f 73  ses the one whos
37560 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  e text encoding.
37570 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 71 75  **          requ
37580 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  ires the least a
37590 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73  mount of convers
375a0 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64 65 66  ion from the def
375b0 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ault.**         
375c0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f   text encoding o
375d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  f the database..
375e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
375f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
37600 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
37610 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
37620 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
37630 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
37640 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
37650 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37660 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
37670 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
37680 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37690 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
376a0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
376b0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
376c0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
376d0 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
376e0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
376f0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
37700 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
37710 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
37720 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
37730 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37740 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
37750 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
37760 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
37770 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
37780 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
37790 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
377a0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
377b0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
377c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
377d0 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
377e0 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b  eded Callbacks {
377f0 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30 30 3e  H16700} <S20300>
37800 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  .**.** To avoid 
37810 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
37820 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
37830 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
37840 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
37850 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
37860 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
37870 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
37880 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
37890 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
378a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
378b0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65  e called wheneve
378c0 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
378d0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
378e0 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
378f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
37900 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
37910 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
37920 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
37930 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
37940 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
37950 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
37960 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
37970 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
37980 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
37990 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
379a0 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69  {H16703} If sqli
379b0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
379c0 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64  eded16() is used
379d0 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61  ,.** the names a
379e0 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46  re passed as UTF
379f0 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e  -16 in machine n
37a00 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
37a10 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65  ..** A call to e
37a20 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
37a30 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73  eplaces any exis
37a40 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  ting callback..*
37a50 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
37a60 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
37a70 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
37a80 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
37a90 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
37aa0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
37ab0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
37ac0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
37ad0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
37ae0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
37af0 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
37b00 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
37b10 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
37b20 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
37b30 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
37b40 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
37b50 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
37b60 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
37b70 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
37b80 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
37b90 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
37ba0 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
37bb0 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
37bc0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
37bd0 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
37be0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
37bf0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
37c00 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
37c10 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20  sequence..**.** 
37c20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
37c30 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
37c40 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
37c50 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
37c60 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
37c70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
37c80 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
37c90 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
37ca0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
37cb0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37cc0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  on_v2()]..**.** 
37cd0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
37ce0 2a 20 7b 48 31 36 37 30 32 7d 20 41 20 73 75 63  * {H16702} A suc
37cf0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
37d00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
37d10 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c 46 29  on_needed(D,P,F)
37d20 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
37d30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
37d40 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c 50  ion_needed16(D,P
37d50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20  ,F)] causes.**  
37d60 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 61 74          the [dat
37d70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37d80 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61  ] D to invoke ca
37d90 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20 66 69  llback F with fi
37da0 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rst.**          
37db0 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e  parameter P when
37dc0 65 76 65 72 20 69 74 20 6e 65 65 64 73 20 61 20  ever it needs a 
37dd0 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
37de0 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20  ion for a.**    
37df0 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
37e00 73 65 71 75 65 6e 63 65 20 74 68 61 74 20 69 74  sequence that it
37e10 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61   does not know a
37e20 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  bout..**.** {H16
37e30 37 30 34 7d 20 45 61 63 68 20 73 75 63 63 65 73  704} Each succes
37e40 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
37e50 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37e60 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20  needed()] or.** 
37e70 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
37e80 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37e90 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69 64 65  ed16()] override
37ea0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  s the callback r
37eb0 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20  egistered.**    
37ec0 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d        on the sam
37ed0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37ee0 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72  ection] by prior
37ef0 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68 65 72   calls to either
37f00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
37f10 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  erface..**.** {H
37f20 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d 65 20  16706} The name 
37f30 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  of the requested
37f40 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37f50 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20 74 68  ion passed in th
37f60 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 34 74  e.**          4t
37f70 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
37f80 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
37f90 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65 20 63  n UTF-8 if the c
37fa0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
37fb0 20 20 20 20 77 61 73 20 72 65 67 69 73 74 65 72      was register
37fc0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
37fd0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37fe0 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ed()] and.**    
37ff0 20 20 20 20 20 20 69 73 20 69 6e 20 55 54 46 2d        is in UTF-
38000 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
38010 72 64 65 72 20 69 66 20 74 68 65 20 63 61 6c 6c  rder if the call
38020 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20  back was.**     
38030 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
38040 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
38050 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
38060 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
38070 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
38080 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33  eeded(.  sqlite3
38090 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20  *, .  void*, .  
380a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
380b0 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
380c0 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  Rep,const char*)
380d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
380e0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
380f0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
38100 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
38110 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
38120 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
38130 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
38140 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
38150 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
38160 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
38170 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
38180 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
38190 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
381a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
381b0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
381c0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
381d0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
381e0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
381f0 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
38200 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
38210 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20   sqlite3_key(.  
38220 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
38230 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
38240 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
38250 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
38260 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
38270 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
38280 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  The key */.);../
38290 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20  *.** Change the 
382a0 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64  key on an open d
382b0 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65  atabase.  If the
382c0 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
382d0 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72  e is not.** encr
382e0 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74  ypted, this rout
382f0 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74  ine will encrypt
38300 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30   it.  If pNew==0
38310 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65   or nNew==0, the
38320 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20  .** database is 
38330 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a  decrypted..**.**
38340 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
38350 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
38360 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
38370 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
38380 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
38390 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
383a0 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c  te3_rekey(.  sql
383b0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
383c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
383d0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
383e0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
383f0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
38400 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
38410 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   new key */.);..
38420 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38430 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f  Suspend Executio
38440 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69  n For A Short Ti
38450 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 34 30  me {H10530} <S40
38460 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  410>.**.** The s
38470 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
38480 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
38490 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
384a0 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
384b0 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
384c0 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
384d0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
384e0 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
384f0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
38500 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
38510 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
38520 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
38530 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
38540 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
38550 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
38560 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
38570 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
38580 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
38590 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
385a0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
385b0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
385c0 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
385d0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
385e0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
385f0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
38600 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
38610 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
38620 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
38630 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
38640 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
38650 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
38660 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
38670 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
38680 20 7b 48 31 30 35 33 33 7d 20 54 68 65 20 5b 73   {H10533} The [s
38690 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d  qlite3_sleep(M)]
386a0 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76 6f 6b   interface invok
386b0 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a  es the xSleep.**
386c0 20 20 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64            method
386d0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
386e0 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 46 53  [sqlite3_vfs|VFS
386f0 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ] in order to.**
38700 20 20 20 20 20 20 20 20 20 20 73 75 73 70 65 6e            suspen
38710 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  d execution of t
38720 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
38730 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a  d for at least.*
38740 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d 69 6c  *          M mil
38750 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a  liseconds..**.**
38760 20 7b 48 31 30 35 33 36 7d 20 54 68 65 20 5b 73   {H10536} The [s
38770 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d  qlite3_sleep(M)]
38780 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
38790 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
387a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 69 6c  .**          mil
387b0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
387c0 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65 71 75  ep actually requ
387d0 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f 70 65  ested of the ope
387e0 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  rating.**       
387f0 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69 63 68     system, which
38800 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72   might be larger
38810 20 74 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65   than the parame
38820 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ter M..*/.int sq
38830 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
38840 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38850 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  F: Name Of The F
38860 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
38870 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 48  mporary Files {H
38880 31 30 33 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a  10310} <S20000>.
38890 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c  **.** If this gl
388a0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
388b0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
388c0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
388d0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d