/ Hex Artifact Content
Login

Artifact 2b8ef43244589ef2d8060b076adaafacda58acf8:


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 30 33 20 32 30 30 38 2f 31  n,v 1.403 2008/1
05f0: 30 2f 31 30 20 32 33 3a 34 38 3a 32 36 20 64 72  0/10 23:48:26 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 0a 2a  e3_errcode()],.*
3cc0: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
3cd0: 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61  te3_errmsg()], a
3ce0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
3cf0: 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  sg16()]..**.** {
3d00: 48 31 32 31 33 38 7d 20 49 66 20 74 68 65 20 53  H12138} If the S
3d10: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
3d20: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
3d30: 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c 20  C,A,E)] is NULL 
3d40: 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  or an.**        
3d50: 20 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f    empty string o
3d60: 72 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 68 69  r contains nothi
3d70: 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68  ng other than wh
3d80: 69 74 65 73 70 61 63 65 2c 20 63 6f 6d 6d 65 6e  itespace, commen
3d90: 74 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ts,.**          
3da0: 61 6e 64 2f 6f 72 20 73 65 6d 69 63 6f 6c 6f 6e  and/or semicolon
3db0: 73 2c 20 74 68 65 6e 20 72 65 73 75 6c 74 73 20  s, then results 
3dc0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  of [sqlite3_errc
3dd0: 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ode()],.**      
3de0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72      [sqlite3_err
3df0: 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  msg()], and [sql
3e00: 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
3e10: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
3e20: 6c 6c 20 72 65 73 65 74 20 74 6f 20 69 6e 64 69  ll reset to indi
3e30: 63 61 74 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a  cate no errors..
3e40: 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
3e50: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 31  S:.**.** {A12141
3e60: 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
3e70: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3e80: 33 5f 65 78 65 63 28 29 5d 20 6d 75 73 74 20 62  3_exec()] must b
3e90: 65 20 61 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f  e an valid and o
3ea0: 70 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  pen.**          
3eb0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3ec0: 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  tion]..**.** {A1
3ed0: 32 31 34 32 7d 20 54 68 65 20 64 61 74 61 62 61  2142} The databa
3ee0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
3ef0: 73 74 20 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64  st not be closed
3f00: 20 77 68 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20   while.**       
3f10: 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63     [sqlite3_exec
3f20: 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ()] is running..
3f30: 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 33 7d 20 54  **.** {A12143} T
3f40: 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
3f50: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 5b  ion should use [
3f60: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
3f70: 74 6f 20 66 72 65 65 0a 2a 2a 20 20 20 20 20 20  to free.**      
3f80: 20 20 20 20 74 68 65 20 6d 65 6d 6f 72 79 20 74      the memory t
3f90: 68 61 74 20 2a 65 72 72 6d 73 67 20 69 73 20 6c  hat *errmsg is l
3fa0: 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 61 74 20  eft pointing at 
3fb0: 6f 6e 63 65 20 74 68 65 20 65 72 72 6f 72 0a 2a  once the error.*
3fc0: 2a 20 20 20 20 20 20 20 20 20 20 6d 65 73 73 61  *          messa
3fd0: 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ge is no longer 
3fe0: 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41  needed..**.** {A
3ff0: 31 32 31 34 35 7d 20 54 68 65 20 53 51 4c 20 73  12145} The SQL s
4000: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
4010: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4020: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  er to [sqlite3_e
4030: 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  xec()].**       
4040: 20 20 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75     must remain u
4050: 6e 63 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b  nchanged while [
4060: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
4070: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69  is running..*/.i
4080: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
4090: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40c0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
40d0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
40e0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
4110: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4120: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4130: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4140: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4150: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4160: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
4170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4190: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
41a0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
41b0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
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 2f 2a 20 45 72 72            /* Err
41e0: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
41f0: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
4200: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
4210: 74 20 43 6f 64 65 73 20 7b 48 31 30 32 31 30 7d  t Codes {H10210}
4220: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59   <S10700>.** KEY
4230: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b  WORDS: SQLITE_OK
4240: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65   {error code} {e
4250: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4260: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4270: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63   code} {result c
4280: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  odes}.**.** Many
4290: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
42a0: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
42b0: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
42c0: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
42d0: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72  wn.** here in or
42e0: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 73  der to indicates
42f0: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
4300: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
4310: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4320: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4330: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4340: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4350: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f  also: [SQLITE_IO
4360: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e  ERR_READ | exten
4370: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4380: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
4390: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
43a0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
43b0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
43c0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
43d0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
43e0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
43f0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4400: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4410: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4420: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4430: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4440: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4450: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4460: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4470: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4480: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
4490: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
44a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44b0: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
44c0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
44d0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
44e0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
44f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4500: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4510: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4520: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4540: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4550: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4560: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4570: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4580: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4590: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
45a0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
45b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
45c0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
45d0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
45e0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
45f0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4600: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4610: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4620: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4630: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4640: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4660: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4670: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4680: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4690: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
46a0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
46b0: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
46c0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
46d0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
46e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46f0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4700: 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54    /* NOT USED. T
4710: 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20 6e  able or record n
4720: 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66  ot found */.#def
4730: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20  ine SQLITE_FULL 
4740: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49         13   /* I
4750: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20  nsertion failed 
4760: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65  because database
4770: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66   is full */.#def
4780: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
4790: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55  PEN    14   /* U
47a0: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68  nable to open th
47b0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
47c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47d0: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35  E_PROTOCOL    15
47e0: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20     /* NOT USED. 
47f0: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
4800: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
4810: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4820: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
4830: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65  /* Database is e
4840: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  mpty */.#define 
4850: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
4860: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
4870: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
4880: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
4890: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
48a0: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
48b0: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
48c0: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
48d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
48e0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
48f0: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
4900: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
4910: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
4920: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
4930: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
4940: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
4950: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4960: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
4970: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
4980: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
4990: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
49a0: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
49b0: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
49c0: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
49d0: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
49e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
49f0: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
4a00: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
4a10: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4a20: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
4a30: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
4a40: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
4a50: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
4a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4a70: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
4a80: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
4a90: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
4aa0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
4ab0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ac0: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
4ad0: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
4ae0: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
4af0: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
4b10: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
4b20: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
4b30: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77   has another row
4b40: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e   ready */.#defin
4b50: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20  e SQLITE_DONE   
4b60: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c       101  /* sql
4b70: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b80: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
4b90: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d  ng */./* end-of-
4ba0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a  error-codes */..
4bb0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4bc0: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
4bd0: 43 6f 64 65 73 20 7b 48 31 30 32 32 30 7d 20 3c  Codes {H10220} <
4be0: 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10700>.** KEYWO
4bf0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65  RDS: {extended e
4c00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65  rror code} {exte
4c10: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
4c20: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
4c30: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c40: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
4c50: 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a  result codes}.**
4c60: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4c70: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4c80: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4c90: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4ca0: 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a   of 26 integer.*
4cb0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72  * [SQLITE_OK | r
4cc0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
4cd0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
4ce0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
4cf0: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
4d00: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
4d10: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
4d20: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
4d30: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
4d40: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
4d50: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
4d60: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
4d70: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
4d80: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
4d90: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
4da0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
4db0: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
4dc0: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65  n 3.3.8 and late
4dd0: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
4de0: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
4df0: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
4e00: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
4e10: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
4e20: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
4e30: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78  t errors. The ex
4e40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4e50: 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  des are enabled 
4e60: 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f  or disabled.** o
4e70: 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65  n a per database
4e80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
4e90: 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  s using the.** [
4ea0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
4eb0: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d  _result_codes()]
4ec0: 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65   API..**.** Some
4ed0: 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c   of the availabl
4ee0: 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
4ef0: 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74  t codes are list
4f00: 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20  ed here..** One 
4f10: 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e  may expect the n
4f20: 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65  umber of extende
4f30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77  d result codes w
4f40: 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a  ill be expand.**
4f50: 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66   over time.  Sof
4f60: 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20  tware that uses 
4f70: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4f80: 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70  codes should exp
4f90: 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65  ect.** to see ne
4fa0: 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69  w result codes i
4fb0: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
4fc0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
4fd0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b  ** The SQLITE_OK
4fe0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c   result code wil
4ff0: 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e  l never be exten
5000: 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c  ded.  It will al
5010: 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74  ways.** be exact
5020: 6c 79 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 49  ly zero..**.** I
5030: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
5040: 20 7b 48 31 30 32 32 33 7d 20 54 68 65 20 73 79   {H10223} The sy
5050: 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20  mbolic name for 
5060: 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  an extended resu
5070: 6c 74 20 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f  lt code shall co
5080: 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ntains.**       
5090: 20 20 20 61 20 72 65 6c 61 74 65 64 20 70 72 69     a related pri
50a0: 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65  mary result code
50b0: 20 61 73 20 61 20 70 72 65 66 69 78 2e 0a 2a 2a   as a prefix..**
50c0: 0a 2a 2a 20 7b 48 31 30 32 32 34 7d 20 50 72 69  .** {H10224} Pri
50d0: 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65  mary result code
50e0: 20 6e 61 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e   names shall con
50f0: 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f  tain a single "_
5100: 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a  " character..**.
5110: 2a 2a 20 7b 48 31 30 32 32 35 7d 20 45 78 74 65  ** {H10225} Exte
5120: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
5130: 20 6e 61 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e   names shall con
5140: 74 61 69 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65  tain two or more
5150: 20 22 5f 22 20 63 68 61 72 61 63 74 65 72 73 2e   "_" characters.
5160: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 36 7d 20  .**.** {H10226} 
5170: 54 68 65 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  The numeric valu
5180: 65 20 6f 66 20 61 6e 20 65 78 74 65 6e 64 65 64  e of an extended
5190: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68 61   result code sha
51a0: 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 68 65 0a 2a  ll contain the.*
51b0: 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 65 72  *          numer
51c0: 69 63 20 76 61 6c 75 65 20 6f 66 20 69 74 73 20  ic value of its 
51d0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 70 72  corresponding pr
51e0: 69 6d 61 72 79 20 72 65 73 75 6c 74 20 63 6f 64  imary result cod
51f0: 65 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  e in.**         
5200: 20 69 74 73 20 6c 65 61 73 74 20 73 69 67 6e 69   its least signi
5210: 66 69 63 61 6e 74 20 38 20 62 69 74 73 2e 0a 2a  ficant 8 bits..*
5220: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5230: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
5240: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5250: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
5260: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5270: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
5280: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5290: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
52a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
52b0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
52c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
52d0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
52e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52f0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
5300: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5310: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
5320: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5330: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
5340: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5350: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
5360: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5370: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
5380: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5390: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
53e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53f0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
5400: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5410: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
5420: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5430: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
5440: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5450: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5460: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
5470: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
5480: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5490: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
54a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
54b0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
54c0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
54d0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
54e0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
54f0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
5500: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5510: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
5520: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
5530: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
5540: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5550: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
5560: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
5570: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
5580: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5590: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
55a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
55b0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
55c0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
55d0: 28 31 35 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20  (15<<8))../*.** 
55e0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
55f0: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
5600: 65 72 61 74 69 6f 6e 73 20 7b 48 31 30 32 33 30  erations {H10230
5610: 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48 31 32 37  } <H11120> <H127
5620: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
5630: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
5640: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
5650: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
5660: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
5670: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5680: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
5690: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
56a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
56b0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20  xOpen method of 
56c0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
56d0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  vfs] object..*/.
56e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
56f0: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
5700: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a       0x00000001.
5710: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5720: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
5730: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
5740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5750: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
5760: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
5770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5780: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
5790: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a  E    0x00000008.
57a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
57b0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
57c0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
57d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
57e0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
57f0: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a       0x00000100.
5800: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5810: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
5820: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
5830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5840: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
5850: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
5860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5870: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
5880: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 0a       0x00000800.
5890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
58a0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
58b0: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a       0x00001000.
58c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
58d0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
58e0: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a       0x00002000.
58f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5900: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
5910: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 0a  AL   0x00004000.
5920: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5930: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20  PEN_NOMUTEX     
5940: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 0a       0x00008000.
5950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5960: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20  PEN_FULLMUTEX   
5970: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 0a       0x00010000.
5980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5990: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
59a0: 72 69 73 74 69 63 73 20 7b 48 31 30 32 34 30 7d  ristics {H10240}
59b0: 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20   <H11120>.**.** 
59c0: 54 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62  The xDeviceCapab
59d0: 69 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f  ilities method o
59e0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
59f0: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62  o_methods].** ob
5a00: 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ject returns an 
5a10: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
5a20: 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65   a vector of the
5a30: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
5a40: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
5a50: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
5a60: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
5a70: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
5a80: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
5a90: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
5aa0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5ab0: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
5ac0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
5ad0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
5ae0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
5af0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
5b00: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
5b10: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
5b20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5b30: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
5b40: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
5b50: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
5b60: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
5b70: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
5b80: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
5b90: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
5ba0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
5bb0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
5bc0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
5bd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5be0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
5bf0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
5c00: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
5c10: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
5c20: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
5c30: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
5c40: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
5c50: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
5c60: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
5c70: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
5c80: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5c90: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
5ca0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
5cb0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
5cc0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
5cd0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
5ce0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
5cf0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
5d00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5d10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
5d20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5d30: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
5d40: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
5d50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5d60: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5d70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
5d80: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5d90: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
5da0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
5db0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5dc0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
5dd0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
5de0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5df0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5e00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
5e10: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5e20: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5e30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
5e40: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5e50: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5e60: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
5e70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
5e80: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5e90: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
5ea0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
5eb0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5ec0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
5ed0: 4e 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30  ND     0x0000020
5ee0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5ef0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
5f00: 4c 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30  L      0x0000040
5f10: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
5f20: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20  F: File Locking 
5f30: 4c 65 76 65 6c 73 20 7b 48 31 30 32 35 30 7d 20  Levels {H10250} 
5f40: 3c 48 31 31 31 32 30 3e 20 3c 48 31 31 33 31 30  <H11120> <H11310
5f50: 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  >.**.** SQLite u
5f60: 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ses one of these
5f70: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
5f80: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
5f90: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
5fa0: 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74  ls it makes to t
5fb0: 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78  he xLock() and x
5fc0: 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73  Unlock() methods
5fd0: 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  .** of an [sqlit
5fe0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
5ff0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
6000: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f  e SQLITE_LOCK_NO
6010: 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64  NE          0.#d
6020: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6030: 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20  K_SHARED        
6040: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6050: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20  _LOCK_RESERVED  
6060: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
6070: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
6080: 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  G       3.#defin
6090: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58  e SQLITE_LOCK_EX
60a0: 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f  CLUSIVE     4../
60b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
60c0: 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54  ynchronization T
60d0: 79 70 65 20 46 6c 61 67 73 20 7b 48 31 30 32 36  ype Flags {H1026
60e0: 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a  0} <H11120>.**.*
60f0: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
6100: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
6110: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
6120: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6130: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
6140: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
6150: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
6160: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6170: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
6180: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
6190: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
61a0: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
61b0: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
61c0: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
61d0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
61e0: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
61f0: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
6200: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
6210: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
6220: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
6230: 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  . The SQLITE_SYN
6240: 43 5f 4e 4f 52 4d 41 4c 20 66 6c 61 67 20 6d 65  C_NORMAL flag me
6250: 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f  ans.** to use no
6260: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
6270: 61 6e 74 69 63 73 2e 20 54 68 65 20 53 51 4c 49  antics. The SQLI
6280: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
6290: 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  g means.** to us
62a0: 65 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c 65  e Mac OS-X style
62b0: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
62c0: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f  d of fsync()..*/
62d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
62e0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
62f0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
6300: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
6310: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
6320: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
6330: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
6340: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
6350: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6360: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
6370: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48  n File Handle {H
6380: 31 31 31 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a  11110} <S20110>.
6390: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
63a0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
63b0: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
63c0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 4f 53  n file in the OS
63d0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 6c 61  .** interface la
63e0: 79 65 72 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  yer.  Individual
63f0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 69 6d   OS interface im
6400: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
6410: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
6420: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
6430: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
6440: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
6450: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
6460: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
6470: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
6480: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
6490: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
64a0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
64b0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
64c0: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
64d0: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
64e0: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
64f0: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
6500: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6510: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
6520: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
6530: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
6540: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6550: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
6560: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
6570: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
6580: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
6590: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
65a0: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
65b0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
65c0: 63 74 20 7b 48 31 31 31 32 30 7d 20 3c 53 32 30  ct {H11120} <S20
65d0: 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  110>.**.** Every
65e0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
65f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6600: 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70  ] xOpen method p
6610: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
6620: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6630: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
6640: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
6650: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
6660: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6670: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
6680: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
6690: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
66a0: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
66b0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
66c0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
66d0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
66e0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
66f0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
6700: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
6710: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
6720: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
6730: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
6740: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
6750: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
6760: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
6770: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
6780: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
6790: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
67a0: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
67b0: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
67c0: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
67d0: 63 20 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c  c OS-X style ful
67e0: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
67f0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
6800: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
6810: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
6820: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
6830: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
6840: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
6850: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
6860: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
6870: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
6880: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
6890: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
68a0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
68b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
68c0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
68d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
68e0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
68f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6900: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
6910: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6920: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
6930: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6940: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
6950: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
6960: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
6970: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
6980: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
6990: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
69a0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
69b0: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
69c0: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
69d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
69e0: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
69f0: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
6a00: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
6a10: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
6a20: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
6a30: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
6a40: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
6a50: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
6a60: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
6a70: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
6a80: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
6a90: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
6aa0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
6ab0: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
6ac0: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
6ad0: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
6ae0: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
6af0: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
6b00: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
6b10: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
6b20: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
6b30: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
6b40: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
6b50: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
6b60: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
6b70: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
6b80: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
6b90: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
6ba0: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
6bb0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
6bc0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
6bd0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
6be0: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
6bf0: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
6c00: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
6c10: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
6c20: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
6c30: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
6c40: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
6c50: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
6c60: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
6c70: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
6c80: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
6c90: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
6ca0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
6cb0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
6cc0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
6cd0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
6ce0: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
6cf0: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
6d00: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
6d10: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
6d20: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
6d30: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
6d40: 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45  se..** A [SQLITE
6d50: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
6d60: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64   | list of opcod
6d70: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30  es] less than 10
6d80: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  0 is available..
6d90: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
6da0: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75  that define a cu
6db0: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f  stom xFileContro
6dc0: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  l method should 
6dd0: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67  use opcodes.** g
6de0: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
6df0: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
6e00: 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ts..**.** The xS
6e10: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
6e20: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
6e30: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
6e40: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
6e50: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
6e60: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
6e70: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
6e80: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
6e90: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
6ea0: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
6eb0: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
6ec0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
6ed0: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
6ee0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
6ef0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
6f00: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
6f10: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
6f20: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
6f30: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
6f40: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
6f50: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6f60: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
6f70: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6f80: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
6f90: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6fa0: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
6fb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6fc0: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
6fd0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6fe0: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
6ff0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7000: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
7010: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7020: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
7030: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7040: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
7050: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7060: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
7070: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7080: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7090: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
70a0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
70b0: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  AL].** </ul>.**.
70c0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
70d0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
70e0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
70f0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
7100: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
7110: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
7120: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
7130: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
7140: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
7150: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
7160: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
7170: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
7180: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
7190: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
71a0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
71b0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
71c0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
71d0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
71e0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
71f0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
7200: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
7210: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
7220: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
7230: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
7240: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
7250: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
7260: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
7270: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
7280: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
7290: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
72a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
72b0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
72c0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
72d0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
72e0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
72f0: 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 74 79 70  xWrite()..*/.typ
7300: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7310: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
7320: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7330: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
7340: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
7350: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
7360: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
7370: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7380: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
7390: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
73a0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
73b0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
73c0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
73d0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
73e0: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
73f0: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7400: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7410: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
7420: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7430: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7440: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
7450: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
7460: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
7470: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
7480: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
7490: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
74a0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
74b0: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
74c0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
74d0: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
74e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
74f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
7500: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
7510: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7520: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
7530: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
7540: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
7550: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
7560: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
7570: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
7580: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7590: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
75a0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
75b0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
75c0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
75d0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
75e0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
75f0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
7600: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
7610: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
7620: 6c 20 4f 70 63 6f 64 65 73 20 7b 48 31 31 33 31  l Opcodes {H1131
7630: 30 7d 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a  0} <S30800>.**.*
7640: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
7650: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
7660: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
7670: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7680: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
7690: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
76a0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
76b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
76c0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
76d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
76e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
76f0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
7700: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
7710: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
7720: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
7730: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
7740: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
7750: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
7760: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
7770: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
7780: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
7790: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
77a0: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
77b0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
77c0: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
77d0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
77e0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
77f0: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
7800: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
7810: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
7820: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
7830: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
7840: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
7850: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  ing and only nee
7860: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
7870: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
7880: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65  EST.** is define
7890: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
78a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
78b0: 54 41 54 45 20 20 20 20 20 20 20 20 31 0a 0a 2f  TATE        1../
78c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
78d0: 75 74 65 78 20 48 61 6e 64 6c 65 20 7b 48 31 37  utex Handle {H17
78e0: 31 31 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a 2a  110} <S20130>.**
78f0: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
7900: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
7910: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
7920: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
7930: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
7940: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
7950: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
7960: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
7970: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
7980: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
7990: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
79a0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
79b0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
79c0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
79d0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
79e0: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
79f0: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
7a00: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
7a10: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
7a20: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
7a30: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
7a40: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
7a50: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
7a60: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7a70: 61 63 65 20 4f 62 6a 65 63 74 20 7b 48 31 31 31  ace Object {H111
7a80: 34 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a  40} <S20100>.**.
7a90: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
7aa0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
7ab0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
7ac0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
7ad0: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
7ae0: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
7af0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
7b00: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
7b10: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
7b20: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
7b30: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
7b40: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
7b50: 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54  system"..**.** T
7b60: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
7b70: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69  iVersion field i
7b80: 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75  s initially 1 bu
7b90: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20  t may be larger 
7ba0: 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72  in.** future ver
7bb0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
7bc0: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65    Additional fie
7bd0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
7be0: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f  ded to this.** o
7bf0: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69  bject when the i
7c00: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73  Version value is
7c10: 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74   increased.  Not
7c20: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
7c30: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
7c40: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
7c50: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
7c60: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74   transaction bet
7c70: 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76  ween.** SQLite v
7c80: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64  ersion 3.5.9 and
7c90: 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74   3.6.0 and yet t
7ca0: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
7cb0: 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64  d was not.** mod
7cc0: 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ified..**.** The
7cd0: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20   szOsFile field 
7ce0: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
7cf0: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73  he subclassed [s
7d00: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20  qlite3_file].** 
7d10: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62  structure used b
7d20: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50  y this VFS.  mxP
7d30: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d  athname is the m
7d40: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
7d50: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69  .** a pathname i
7d60: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a  n this VFS..**.*
7d70: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c  * Registered sql
7d80: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73  ite3_vfs objects
7d90: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c   are kept on a l
7da0: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65  inked list forme
7db0: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78  d by.** the pNex
7dc0: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  t pointer.  The 
7dd0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67  [sqlite3_vfs_reg
7de0: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20  ister()].** and 
7df0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72  [sqlite3_vfs_unr
7e00: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72  egister()] inter
7e10: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69  faces manage thi
7e20: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74  s list.** in a t
7e30: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20  hread-safe way. 
7e40: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
7e50: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66  s_find()] interf
7e60: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20  ace.** searches 
7e70: 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68  the list.  Neith
7e80: 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
7e90: 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20  on code nor the 
7ea0: 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  VFS.** implement
7eb0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ation should use
7ec0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
7ed0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e  er..**.** The pN
7ee0: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65  ext field is the
7ef0: 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74   only field in t
7f00: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
7f10: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  * structure that
7f20: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65   SQLite will eve
7f30: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74  r modify.  SQLit
7f40: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65  e will only acce
7f50: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20  ss.** or modify 
7f60: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65  this field while
7f70: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69   holding a parti
7f80: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74  cular static mut
7f90: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ex..** The appli
7fa0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
7fb0: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68  ver modify anyth
7fc0: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73  ing within the s
7fd0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62  qlite3_vfs.** ob
7fe0: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62  ject once the ob
7ff0: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65  ject has been re
8000: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  gistered..**.** 
8010: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20  The zName field 
8020: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f  holds the name o
8030: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65  f the VFS module
8040: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74  .  The name must
8050: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63  .** be unique ac
8060: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64  ross all VFS mod
8070: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  ules..**.** {H11
8080: 31 34 31 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  141} SQLite will
8090: 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
80a0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
80b0: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
80c0: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
80d0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
80e0: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
80f0: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
8100: 68 6e 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65  hname().  SQLite
8110: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
8120: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
8130: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
8140: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
8150: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
8160: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
8170: 7b 45 4e 44 7d 20 20 42 65 63 61 75 73 65 20 6f  {END}  Because o
8180: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
8190: 65 6e 74 65 6e 73 65 2c 0a 2a 2a 20 74 68 65 20  entense,.** the 
81a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
81b0: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
81c0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
81d0: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
81e0: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
81f0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
8200: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
8210: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
8220: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
8230: 20 69 73 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   is xOpen is a N
8240: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
8250: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
8260: 6e 76 69 74 65 20 69 74 73 20 6f 77 6e 20 74 65  nvite its own te
8270: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
8280: 20 74 68 65 20 66 69 6c 65 2e 20 20 57 68 65 6e   the file.  When
8290: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
82a0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
82b0: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
82c0: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
82d0: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
82e0: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
82f0: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
8300: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8310: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  CLOSE]..**.** {H
8320: 31 31 31 34 32 7d 20 54 68 65 20 66 6c 61 67 73  11142} The flags
8330: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
8340: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
8350: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
8360: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
8370: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
8380: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
8390: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
83a0: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
83b0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
83c0: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
83d0: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
83e0: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
83f0: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
8400: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
8410: 41 54 45 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49  ATE]. {END}.** I
8420: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
8430: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
8440: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
8450: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
8460: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
8470: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
8480: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
8490: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
84a0: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31  set..**.** {H111
84b0: 34 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  43} SQLite will 
84c0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
84d0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
84e0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
84f0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
8500: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
8510: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
8520: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8530: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8540: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
8550: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8560: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
8570: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8580: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
8590: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
85a0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
85b0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
85c0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
85d0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
85e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
85f0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
8600: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
8610: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
8620: 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a  * </ul> {END}.**
8630: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
8640: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
8650: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
8660: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
8670: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
8680: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
8690: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
86a0: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
86b0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
86c0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
86d0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
86e0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
86f0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
8700: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
8710: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
8720: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
8730: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
8740: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
8750: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
8760: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
8770: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
8780: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
8790: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
87a0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
87b0: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
87c0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
87d0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
87e0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
87f0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
8800: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
8810: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
8820: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
8830: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
8840: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
8850: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
8860: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
8870: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
8880: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
8890: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
88a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
88b0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
88c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
88d0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
88e0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  </ul>.**.** {H11
88f0: 31 34 35 7d 20 54 68 65 20 5b 53 51 4c 49 54 45  145} The [SQLITE
8900: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
8910: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
8920: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
8930: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
8940: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
8950: 20 20 7b 48 31 31 31 34 36 7d 20 54 68 65 20 5b    {H11146} The [
8960: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8970: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
8980: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
8990: 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a  MP  databases, j
89a0: 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20  ournals and for 
89b0: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
89c0: 2a 2a 20 7b 48 31 31 31 34 37 7d 20 54 68 65 20  ** {H11147} The 
89d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
89e0: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 6d 65 61  LUSIVE] flag mea
89f0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
8a00: 6c 64 20 62 65 20 6f 70 65 6e 65 64 0a 2a 2a 20  ld be opened.** 
8a10: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
8a20: 63 65 73 73 2e 20 20 54 68 69 73 20 66 6c 61 67  cess.  This flag
8a30: 20 69 73 20 73 65 74 20 66 6f 72 20 61 6c 6c 20   is set for all 
8a40: 66 69 6c 65 73 20 65 78 63 65 70 74 0a 2a 2a 20  files except.** 
8a50: 66 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74  for the main dat
8a60: 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
8a70: 2a 20 7b 48 31 31 31 34 38 7d 20 41 74 20 6c 65  * {H11148} At le
8a80: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
8a90: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
8aa0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
8ab0: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
8ac0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
8ad0: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
8ae0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
8af0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
8b00: 20 78 4f 70 65 6e 2e 20 7b 45 4e 44 7d 20 20 54   xOpen. {END}  T
8b10: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
8b20: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
8b30: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
8b40: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
8b50: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
8b60: 69 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  it in..**.** {H1
8b70: 31 31 34 39 7d 20 54 68 65 20 66 6c 61 67 73 20  1149} The flags 
8b80: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
8b90: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
8ba0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
8bb0: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
8bc0: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
8bd0: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
8be0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
8bf0: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
8c00: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
8c10: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
8c20: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
8c30: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
8c40: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
8c50: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
8c60: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
8c70: 62 6c 65 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20  ble. {END}  The 
8c80: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
8c90: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
8ca0: 2a 20 7b 48 31 31 31 35 30 7d 20 53 51 4c 69 74  * {H11150} SQLit
8cb0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
8cc0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
8cd0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
8ce0: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
8cf0: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
8d00: 6c 50 61 74 68 6e 61 6d 65 2e 20 7b 48 31 31 31  lPathname. {H111
8d10: 35 31 7d 20 54 68 65 20 65 78 61 63 74 20 73 69  51} The exact si
8d20: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
8d30: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
8d40: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
8d50: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
8d60: 20 20 6d 65 74 68 6f 64 73 2e 20 7b 45 4e 44 7d    methods. {END}
8d70: 20 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20    If the output 
8d80: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
8d90: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
8da0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
8db0: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
8dc0: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
8dd0: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
8de0: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
8df0: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
8e00: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
8e10: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
8e20: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
8e30: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
8e40: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
8e50: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
8e60: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
8e70: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
8e80: 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75  Sleep(), and xCu
8e90: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65  rrentTime() inte
8ea0: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
8eb0: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
8ec0: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
8ed0: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
8ee0: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
8ef0: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
8f00: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
8f10: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
8f20: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
8f30: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
8f40: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
8f50: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
8f60: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
8f70: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
8f80: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
8f90: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
8fa0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
8fb0: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
8fc0: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
8fd0: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
8fe0: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
8ff0: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
9000: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
9010: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
9020: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
9030: 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74  n.  The xCurrent
9040: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
9050: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
9060: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
9070: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
9080: 65 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2f 0a 74  e and time..*/.t
9090: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
90a0: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
90b0: 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71  3_vfs;.struct sq
90c0: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
90d0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
90e0: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
90f0: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
9100: 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  er */.  int szOs
9110: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
9120: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
9130: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
9140: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
9150: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
9160: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
9170: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
9180: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
9190: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
91a0: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
91b0: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
91c0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
91d0: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
91e0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
91f0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
9200: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
9210: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
9220: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
9230: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
9240: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
9250: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9260: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
9270: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
9280: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
9290: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
92a0: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
92b0: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
92c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
92d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
92e0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
92f0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
9300: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
9310: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
9320: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
9330: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
9340: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
9350: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
9360: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
9370: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
9380: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
9390: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
93a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
93b0: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
93c0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
93d0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
93e0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
93f0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
9400: 69 64 20 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  id *(*xDlSym)(sq
9410: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
9420: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
9430: 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f 69 64 20 28  ymbol);.  void (
9440: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
9450: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
9460: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
9470: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
9480: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
9490: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
94a0: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
94b0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
94c0: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
94d0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
94e0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
94f0: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
9500: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
9510: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9520: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
9530: 2f 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  /* New fields ma
9540: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
9550: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
9560: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
9570: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
9580: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
9590: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
95a0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
95b0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
95c0: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
95d0: 53 20 6d 65 74 68 6f 64 20 7b 48 31 31 31 39 30  S method {H11190
95e0: 7d 20 3c 48 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a  } <H11140>.**.**
95f0: 20 7b 48 31 31 31 39 31 7d 20 54 68 65 73 65 20   {H11191} These 
9600: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
9610: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
9620: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
9630: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
9640: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
9650: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
9660: 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d 20  ] object. {END} 
9670: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
9680: 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
9690: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
96a0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
96b0: 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a  s looking for..*
96c0: 2a 20 7b 48 31 31 31 39 32 7d 20 57 69 74 68 20  * {H11192} With 
96d0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
96e0: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
96f0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
9700: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
9710: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
9720: 73 2e 0a 2a 2a 20 7b 48 31 31 31 39 33 7d 20 57  s..** {H11193} W
9730: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
9740: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
9750: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
9760: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
9770: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f  r the file is bo
9780: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
9790: 77 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 7b 48 31  writable..** {H1
97a0: 31 31 39 34 7d 20 57 69 74 68 20 53 51 4c 49 54  1194} With SQLIT
97b0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
97c0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
97d0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
97e0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
97f0: 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65  readable..*/.#de
9800: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
9810: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
9820: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
9830: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
9840: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9850: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
9860: 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   2../*.** CAPI3R
9870: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
9880: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
9890: 79 20 7b 48 31 30 31 33 30 7d 20 3c 53 32 30 30  y {H10130} <S200
98a0: 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a  00><S30100>.**.*
98b0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
98c0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
98d0: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
98e0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
98f0: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
9900: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
9910: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
9920: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
9930: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
9940: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
9950: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
9960: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
9970: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9980: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
9990: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
99a0: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
99b0: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
99c0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
99d0: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
99e0: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
99f0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
9a00: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
9a10: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
9a20: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
9a30: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
9a40: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
9a50: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9a60: 28 29 2e 20 20 4f 6e 6c 79 20 61 6e 20 65 66 66  ().  Only an eff
9a70: 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
9a80: 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
9a90: 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
9aa0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
9ab0: 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
9ac0: 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
9ad0: 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41   no-ops..**.** A
9ae0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
9af0: 73 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  s, sqlite3_initi
9b00: 61 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69 6e  alize() shall in
9b10: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
9b20: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
9b30: 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  larly, sqlite3_s
9b40: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68 61  hutdown().** sha
9b50: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
9b60: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
9b70: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
9b80: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
9b90: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
9ba0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
9bb0: 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f 6d  s..** If for som
9bc0: 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65  e reason, sqlite
9bd0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
9be0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74  s unable to init
9bf0: 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69  ialize.** the li
9c00: 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69  brary (perhaps i
9c10: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  t is unable to a
9c20: 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64  llocate a needed
9c30: 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a   resource such.*
9c40: 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74  * as a mutex) it
9c50: 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72   returns an [err
9c60: 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74  or code] other t
9c70: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  han [SQLITE_OK].
9c80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
9c90: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9ca0: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
9cb0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
9cc0: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
9cd0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
9ce0: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
9cf0: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
9d00: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
9d10: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
9d20: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
9d30: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
9d40: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
9d50: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
9d60: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9d70: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
9d80: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
9d90: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
9da0: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
9db0: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
9dc0: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
9dd0: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
9de0: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
9df0: 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 65 76   already.  Howev
9e00: 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73  er, if SQLite is
9e10: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
9e20: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
9e30: 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d  AUTOINIT].** com
9e40: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
9e50: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d  , then the autom
9e60: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71  atic calls to sq
9e70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9e80: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65  ().** are omitte
9e90: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  d and the applic
9ea0: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20  ation must call 
9eb0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9ec0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a  ze() directly.**
9ed0: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
9ee0: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
9ef0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72   interface.  For
9f00: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
9f10: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72  lity,.** it is r
9f20: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
9f30: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77  applications alw
9f40: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ays invoke sqlit
9f50: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
9f60: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f  ** directly prio
9f70: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
9f80: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
9f90: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72  rface.  Future r
9fa0: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51  eleases.** of SQ
9fb0: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65  Lite may require
9fc0: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72   this.  In other
9fd0: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61   words, the beha
9fe0: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a  vior exhibited.*
9ff0: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
a000: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
a010: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
a020: 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f  INIT] might beco
a030: 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  me the.** defaul
a040: 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f  t behavior in so
a050: 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
a060: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
a070: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
a080: 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65  s_init() routine
a090: 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d   does operating-
a0a0: 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a  system specific.
a0b0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ** initializatio
a0c0: 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  n of the SQLite 
a0d0: 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71  library.  The sq
a0e0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
a0f0: 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
a100: 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73   the effect of s
a110: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a120: 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73  .  Typical tasks
a130: 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79  .** performed by
a140: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
a150: 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69  include allocati
a160: 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69  on or deallocati
a170: 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20  on.** of static 
a180: 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69  resources, initi
a190: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f  alization of glo
a1a0: 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a  bal variables,.*
a1b0: 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64  * setting up a d
a1c0: 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
a1d0: 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20  vfs] module, or 
a1e0: 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20  setting up.** a 
a1f0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
a200: 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c  ation using [sql
a210: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
a220: 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
a230: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
a240: 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  er invoke either
a250: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a260: 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
a270: 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74  _os_end() direct
a280: 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  ly.  The applica
a290: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  tion should only
a2a0: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
a2b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
a2c0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74  and sqlite3_shut
a2d0: 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c  down().  The sql
a2e0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
a2f0: 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63  * interface is c
a300: 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61  alled automatica
a310: 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69  lly by sqlite3_i
a320: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a  nitialize() and.
a330: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ** sqlite3_os_en
a340: 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79  d() is called by
a350: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
a360: 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74  n().  Appropriat
a370: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
a380: 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33  ions for sqlite3
a390: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
a3a0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
a3b0: 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74  ** are built int
a3c0: 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74  o SQLite when it
a3d0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
a3e0: 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20   unix, windows, 
a3f0: 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e  or os/2..** When
a400: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
a410: 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e   platforms (usin
a420: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
a430: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
a440: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
a450: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
a460: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
a470: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
a480: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
a490: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a4a0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
a4b0: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
a4c0: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
a4d0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a4e0: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
a4f0: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
a500: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
a510: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
a520: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
a530: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
a540: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
a550: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
a560: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
a570: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
a580: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
a590: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
a5a0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
a5b0: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
a5c0: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
a5d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a5e0: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
a5f0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20   SQLite Library 
a600: 7b 48 31 34 31 30 30 7d 20 3c 53 32 30 30 30 30  {H14100} <S20000
a610: 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50  ><S30200>.** EXP
a620: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
a630: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
a640: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
a650: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
a660: 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
a670: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
a680: 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
a690: 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
a6a0: 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
a6b0: 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
a6c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
a6d0: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
a6e0: 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
a6f0: 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
a700: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
a710: 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
a720: 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
a730: 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
a740: 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
a750: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
a760: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
a770: 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
a780: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
a790: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
a7a0: 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74  terface is not t
a7b0: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20  hreadsafe.  The 
a7c0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
a7d0: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
a7e0: 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  no other SQLite 
a7f0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
a800: 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a  nvoked by other.
a810: 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65  ** threads while
a820: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
a830: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46  ) is running.  F
a840: 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69  urthermore, sqli
a850: 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20  te3_config().** 
a860: 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
a870: 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
a880: 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
a890: 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
a8a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a8b0: 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
a8c0: 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
a8d0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
a8e0: 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
a8f0: 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f   that sqlite3_co
a900: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
a910: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
a920: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
a930: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
a940: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
a950: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
a960: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
a970: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
a980: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
a990: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
a9a0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
a9b0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c  G_SINGLETHREAD |
a9c0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
a9d0: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
a9e0: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
a9f0: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
aa00: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
aa10: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
aa20: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
aa30: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
aa40: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  n the [SQLITE_CO
aa50: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
aa60: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  D | configuratio
aa70: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
aa80: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
aa90: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61  nt..**.** When a
aaa0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
aab0: 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71  ption is set, sq
aac0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72  lite3_config() r
aad0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
aae0: 4b 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  K]..** If the op
aaf0: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
ab00: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
ab10: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
ab20: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
ab30: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
ab40: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
ab50: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
ab60: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
ab70: 0a 2a 2a 20 7b 48 31 34 31 30 33 7d 20 41 20 73  .** {H14103} A s
ab80: 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
ab90: 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
aba0: 5f 63 6f 6e 66 69 67 28 29 5d 20 73 68 61 6c 6c  _config()] shall
abb0: 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
abc0: 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e      [SQLITE_OK].
abd0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 30 36 7d 20  .**.** {H14106} 
abe0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
abf0: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
ac00: 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53   shall return [S
ac10: 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 0a 2a 2a  QLITE_MISUSE].**
ac20: 20 20 20 20 20 20 20 20 20 20 69 66 20 69 74 20            if it 
ac30: 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 62 65  is invoked in be
ac40: 74 77 65 65 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  tween calls to [
ac50: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ac60: 7a 65 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ze()] and.**    
ac70: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
ac80: 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a  hutdown()]..**.*
ac90: 2a 20 7b 48 31 34 31 32 30 7d 20 41 20 73 75 63  * {H14120} A suc
aca0: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
acb0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
acc0: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
acd0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 29 0a 2a  SINGLETHREAD]).*
ace0: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
acf0: 20 73 65 74 20 74 68 65 20 64 65 66 61 75 6c 74   set the default
ad00: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
ad10: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
ad20: 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32  ad..**.** {H1412
ad30: 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  3} A successful 
ad40: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
ad50: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
ad60: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
ad70: 45 41 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20  EAD]).**        
ad80: 20 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20    shall set the 
ad90: 64 65 66 61 75 6c 74 20 5b 74 68 72 65 61 64 69  default [threadi
ada0: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74  ng mode] to Mult
adb0: 69 2d 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  i-thread..**.** 
adc0: 7b 48 31 34 31 32 36 7d 20 41 20 73 75 63 63 65  {H14126} A succe
add0: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
ade0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
adf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
ae00: 52 49 41 4c 49 5a 45 44 5d 29 0a 2a 2a 20 20 20  RIALIZED]).**   
ae10: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65 74         shall set
ae20: 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68   the default [th
ae30: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
ae40: 20 53 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a   Serialized..**.
ae50: 2a 2a 20 7b 48 31 34 31 32 39 7d 20 41 20 73 75  ** {H14129} A su
ae60: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
ae70: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
ae80: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
ae90: 5f 4d 55 54 45 58 5d 2c 58 29 0a 2a 2a 20 20 20  _MUTEX],X).**   
aea0: 20 20 20 20 20 20 20 77 68 65 72 65 20 58 20 69         where X i
aeb0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
aec0: 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 5b 73  n initialized [s
aed0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
aee0: 68 6f 64 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  hods].**        
aef0: 20 20 6f 62 6a 65 63 74 20 73 68 61 6c 6c 20 63    object shall c
af00: 61 75 73 65 20 61 6c 6c 20 73 75 62 73 65 71 75  ause all subsequ
af10: 65 6e 74 20 6d 75 74 65 78 20 6f 70 65 72 61 74  ent mutex operat
af20: 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 0a 2a  ions performed.*
af30: 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 53 51  *          by SQ
af40: 4c 69 74 65 20 74 6f 20 75 73 65 20 74 68 65 20  Lite to use the 
af50: 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20 74 68  mutex methods th
af60: 61 74 20 77 65 72 65 20 70 72 65 73 65 6e 74 20  at were present 
af70: 69 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20  in X.**         
af80: 20 64 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c   during the call
af90: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
afa0: 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  fig()]..**.** {H
afb0: 31 34 31 33 32 7d 20 41 20 73 75 63 63 65 73 73  14132} A success
afc0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
afd0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
afe0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
aff0: 55 54 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20  UTEX],X).**     
b000: 20 20 20 20 20 77 68 65 72 65 20 58 20 69 73 20       where X is 
b010: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
b020: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
b030: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 0a  ethods] object .
b040: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
b050: 6c 20 6f 76 65 72 77 72 69 74 65 20 74 68 65 20  l overwrite the 
b060: 63 6f 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69  content of [sqli
b070: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
b080: 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 20 20 20  s] object.**    
b090: 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20 6d        with the m
b0a0: 75 74 65 78 20 6d 65 74 68 6f 64 73 20 63 75 72  utex methods cur
b0b0: 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 20 62 79  rently in use by
b0c0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b   SQLite..**.** {
b0d0: 48 31 34 31 33 35 7d 20 41 20 73 75 63 63 65 73  H14135} A succes
b0e0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
b0f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
b100: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
b110: 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20 20 20  LOC],M).**      
b120: 20 20 20 20 77 68 65 72 65 20 4d 20 69 73 20 61      where M is a
b130: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
b140: 6e 69 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c 69  nitialized [sqli
b150: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
b160: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a  .**          obj
b170: 65 63 74 20 73 68 61 6c 6c 20 63 61 75 73 65 20  ect shall cause 
b180: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6d  all subsequent m
b190: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b1a0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 20   operations.**  
b1b0: 20 20 20 20 20 20 20 20 70 65 72 66 6f 72 6d 65          performe
b1c0: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 75  d by SQLite to u
b1d0: 73 65 20 74 68 65 20 6d 65 74 68 6f 64 73 20 74  se the methods t
b1e0: 68 61 74 20 77 65 72 65 20 70 72 65 73 65 6e 74  hat were present
b1f0: 20 69 6e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   in .**         
b200: 20 4d 20 64 75 72 69 6e 67 20 74 68 65 20 63 61   M during the ca
b210: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
b220: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
b230: 7b 48 31 34 31 33 38 7d 20 41 20 73 75 63 63 65  {H14138} A succe
b240: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
b250: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
b260: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
b270: 54 4d 41 4c 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20  TMALLOC],M).**  
b280: 20 20 20 20 20 20 20 20 77 68 65 72 65 20 4d 20          where M 
b290: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
b2a0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  an [sqlite3_mem_
b2b0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
b2c0: 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  shall.**        
b2d0: 20 20 6f 76 65 72 77 72 69 74 65 20 74 68 65 20    overwrite the 
b2e0: 63 6f 6e 74 65 6e 74 20 6f 66 20 5b 73 71 6c 69  content of [sqli
b2f0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
b300: 20 6f 62 6a 65 63 74 20 77 69 74 68 20 0a 2a 2a   object with .**
b310: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65            the me
b320: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b330: 6d 65 74 68 6f 64 73 20 63 75 72 72 65 6e 74 6c  methods currentl
b340: 79 20 69 6e 20 75 73 65 20 62 79 0a 2a 2a 20 20  y in use by.**  
b350: 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 2e 0a          SQLite..
b360: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 31 7d 20 41  **.** {H14141} A
b370: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
b380: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
b390: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
b3a0: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 31  FIG_MEMSTATUS],1
b3b0: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ).**          sh
b3c0: 61 6c 6c 20 65 6e 61 62 6c 65 20 74 68 65 20 6d  all enable the m
b3d0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b3e0: 20 73 74 61 74 75 73 20 63 6f 6c 6c 65 63 74 69   status collecti
b3f0: 6f 6e 20 6c 6f 67 69 63 2e 0a 2a 2a 0a 2a 2a 20  on logic..**.** 
b400: 7b 48 31 34 31 34 34 7d 20 41 20 73 75 63 63 65  {H14144} A succe
b410: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
b420: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
b430: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
b440: 4d 53 54 41 54 55 53 5d 2c 30 29 0a 2a 2a 20 20  MSTATUS],0).**  
b450: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 64 69          shall di
b460: 73 61 62 6c 65 20 74 68 65 20 6d 65 6d 6f 72 79  sable the memory
b470: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
b480: 75 73 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f  us collection lo
b490: 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31  gic..**.** {H141
b4a0: 34 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  47} The memory a
b4b0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73  llocation status
b4c0: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69   collection logi
b4d0: 63 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20  c shall be.**   
b4e0: 20 20 20 20 20 20 20 65 6e 61 62 6c 65 64 20 62         enabled b
b4f0: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
b500: 20 7b 48 31 34 31 35 30 7d 20 41 20 73 75 63 63   {H14150} A succ
b510: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
b520: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
b530: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
b540: 43 52 41 54 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a  CRATCH],S,Z,N).*
b550: 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65  *          where
b560: 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e   Z and N are non
b570: 2d 6e 65 67 61 74 69 76 65 20 69 6e 74 65 67 65  -negative intege
b580: 72 73 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20  rs and .**      
b590: 20 20 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74      S is a point
b5a0: 65 72 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64  er to an aligned
b5b0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e   memory buffer n
b5c0: 6f 74 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20  ot less than.** 
b5d0: 20 20 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74           Z*N byt
b5e0: 65 73 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c  es in size shall
b5f0: 20 63 61 75 73 65 20 53 20 74 6f 20 62 65 20 75   cause S to be u
b600: 73 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  sed by the.**   
b610: 20 20 20 20 20 20 20 5b 73 63 72 61 74 63 68 20         [scratch 
b620: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
b630: 5d 20 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73  ] for as many as
b640: 20 4e 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73   N simulataneous
b650: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c  .**          all
b660: 6f 63 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66  ocations each of
b670: 20 73 69 7a 65 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b   size Z..**.** {
b680: 48 31 34 31 35 33 7d 20 41 20 73 75 63 63 65 73  H14153} A succes
b690: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
b6a0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
b6b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
b6c0: 41 54 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20  ATCH],S,Z,N).** 
b6d0: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 53           where S
b6e0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
b6f0: 65 72 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65  er shall disable
b700: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
b710: 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79   [scratch memory
b720: 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a   allocator]..**.
b730: 2a 2a 20 7b 48 31 34 31 35 36 7d 20 41 20 73 75  ** {H14156} A su
b740: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
b750: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
b760: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
b770: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
b780: 45 43 41 43 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a  ECACHE],S,Z,N).*
b790: 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65  *          where
b7a0: 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e   Z and N are non
b7b0: 2d 6e 65 67 61 74 69 76 65 20 69 6e 74 65 67 65  -negative intege
b7c0: 72 73 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20  rs and .**      
b7d0: 20 20 20 20 53 20 69 73 20 61 20 70 6f 69 6e 74      S is a point
b7e0: 65 72 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64  er to an aligned
b7f0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6e   memory buffer n
b800: 6f 74 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20  ot less than.** 
b810: 20 20 20 20 20 20 20 20 20 5a 2a 4e 20 62 79 74           Z*N byt
b820: 65 73 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c  es in size shall
b830: 20 63 61 75 73 65 20 53 20 74 6f 20 62 65 20 75   cause S to be u
b840: 73 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  sed by the.**   
b850: 20 20 20 20 20 20 20 5b 70 61 67 65 63 61 63 68         [pagecach
b860: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
b870: 6f 72 5d 20 66 6f 72 20 61 73 20 6d 61 6e 79 20  or] for as many 
b880: 61 73 20 4e 20 73 69 6d 75 6c 61 74 61 6e 65 6f  as N simulataneo
b890: 75 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  us.**          a
b8a0: 6c 6c 6f 63 61 74 69 6f 6e 73 20 65 61 63 68 20  llocations each 
b8b0: 6f 66 20 73 69 7a 65 20 5a 2e 0a 2a 2a 0a 2a 2a  of size Z..**.**
b8c0: 20 7b 48 31 34 31 35 39 7d 20 41 20 73 75 63 63   {H14159} A succ
b8d0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a  essful call to.*
b8e0: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
b8f0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
b900: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
b910: 41 43 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20  ACHE],S,Z,N).** 
b920: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 53           where S
b930: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
b940: 65 72 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65  er shall disable
b950: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
b960: 20 5b 70 61 67 65 63 61 63 68 65 20 6d 65 6d 6f   [pagecache memo
b970: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a  ry allocator]..*
b980: 2a 0a 2a 2a 20 7b 48 31 34 31 36 32 7d 20 41 20  *.** {H14162} A 
b990: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
b9a0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
b9b0: 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
b9c0: 49 47 5f 48 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a  IG_HEAP],H,Z,N).
b9d0: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72  **          wher
b9e0: 65 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 6e 6f  e Z and N are no
b9f0: 6e 2d 6e 65 67 61 74 69 76 65 20 69 6e 74 65 67  n-negative integ
ba00: 65 72 73 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20  ers and .**     
ba10: 20 20 20 20 20 48 20 69 73 20 61 20 70 6f 69 6e       H is a poin
ba20: 74 65 72 20 74 6f 20 61 6e 20 61 6c 69 67 6e 65  ter to an aligne
ba30: 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  d memory buffer 
ba40: 6e 6f 74 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a  not less than.**
ba50: 20 20 20 20 20 20 20 20 20 20 5a 20 62 79 74 65            Z byte
ba60: 73 20 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20  s in size shall 
ba70: 65 6e 61 62 6c 65 20 74 68 65 20 5b 6d 65 6d 73  enable the [mems
ba80: 79 73 35 5d 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ys5] memory allo
ba90: 63 61 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  cator.**        
baa0: 20 20 61 6e 64 20 63 61 75 73 65 20 69 74 20 74    and cause it t
bab0: 6f 20 75 73 65 20 62 75 66 66 65 72 20 53 20 61  o use buffer S a
bac0: 73 20 69 74 73 20 6d 65 6d 6f 72 79 20 73 6f 75  s its memory sou
bad0: 72 63 65 20 61 6e 64 20 74 6f 20 75 73 65 0a 2a  rce and to use.*
bae0: 2a 20 20 20 20 20 20 20 20 20 20 61 20 6d 69 6e  *          a min
baf0: 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
bb00: 73 69 7a 65 20 6f 66 20 4e 2e 0a 2a 2a 0a 2a 2a  size of N..**.**
bb10: 20 7b 48 31 34 31 36 35 7d 20 41 20 73 75 63 63   {H14165} A succ
bb20: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
bb30: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
bb40: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
bb50: 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20  EAP],H,Z,N).**  
bb60: 20 20 20 20 20 20 20 20 77 68 65 72 65 20 48 20          where H 
bb70: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
bb80: 72 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20  r shall disable 
bb90: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
bba0: 5b 6d 65 6d 73 79 73 35 5d 20 6d 65 6d 6f 72 79  [memsys5] memory
bbb0: 20 61 6c 6c 6f 63 61 74 6f 72 2e 0a 2a 2a 0a 2a   allocator..**.*
bbc0: 2a 20 7b 48 31 34 31 36 38 7d 20 41 20 73 75 63  * {H14168} A suc
bbd0: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
bbe0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
bbf0: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
bc00: 4c 4f 4f 4b 41 53 49 44 45 5d 2c 5a 2c 4e 29 0a  LOOKASIDE],Z,N).
bc10: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
bc20: 6c 20 63 61 75 73 65 20 74 68 65 20 64 65 66 61  l cause the defa
bc30: 75 6c 74 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  ult [lookaside m
bc40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
bc50: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
bc60: 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 6e  *          for n
bc70: 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ew [database con
bc80: 6e 65 63 74 69 6f 6e 73 5d 20 74 6f 20 62 65 20  nections] to be 
bc90: 4e 20 73 6c 6f 74 73 20 6f 66 20 5a 20 62 79 74  N slots of Z byt
bca0: 65 73 20 65 61 63 68 2e 0a 2a 2f 0a 53 51 4c 49  es each..*/.SQLI
bcb0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
bcc0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  int sqlite3_conf
bcd0: 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f  ig(int, ...);../
bce0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
bcf0: 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73  onfigure databas
bd00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20 7b  e connections  {
bd10: 48 31 34 32 30 30 7d 20 3c 53 32 30 30 30 30 3e  H14200} <S20000>
bd20: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
bd30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
bd40: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
bd50: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
bd60: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
bd70: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
bd80: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
bd90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
bda0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
bdb0: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
bdc0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
bdd0: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
bde0: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
bdf0: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
be00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
be10: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
be20: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
be30: 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73  ment).  The.** s
be40: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
be50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
be60: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69 6d   only be used im
be70: 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 0a  mediately after.
be80: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
be90: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 72  connection is cr
bea0: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
beb0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a  ite3_open()],.**
bec0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
bed0: 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
bee0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a  _open_v2()].  .*
bef0: 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
bf00: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
bf10: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
bf20: 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
bf30: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
bf40: 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67 65  verb - an intege
bf50: 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64 69  r code that indi
bf60: 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61 73  cates what.** as
bf70: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
bf80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bf90: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
bfa0: 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e  gured..** The on
bfb0: 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68  ly choice for th
bfc0: 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51 4c  is value is [SQL
bfd0: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
bfe0: 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20  KASIDE]..** New 
bff0: 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79  verbs are likely
c000: 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20   to be added in 
c010: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
c020: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41 64  of SQLite..** Ad
c030: 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
c040: 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68 65  ts depend on the
c050: 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   verb..**.** INV
c060: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
c070: 48 31 34 32 30 33 7d 20 41 20 63 61 6c 6c 20 74  H14203} A call t
c080: 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
c090: 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 5d 20 73  nfig(D,V,...)] s
c0a0: 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  hall return [SQL
c0b0: 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 20 20 20 20 20  ITE_OK].**      
c0c0: 20 20 20 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20      if and only 
c0d0: 69 66 20 74 68 65 20 63 61 6c 6c 20 69 73 20 73  if the call is s
c0e0: 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a  uccessful..**.**
c0f0: 20 7b 48 31 34 32 30 36 7d 20 49 66 20 6f 6e 65   {H14206} If one
c100: 20 6f 72 20 6d 6f 72 65 20 73 6c 6f 74 73 20 6f   or more slots o
c110: 66 20 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64 65  f the [lookaside
c120: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
c130: 72 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  r] for.**       
c140: 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
c150: 6e 65 63 74 69 6f 6e 5d 20 44 20 61 72 65 20 69  nection] D are i
c160: 6e 20 75 73 65 2c 20 74 68 65 6e 20 61 20 63 61  n use, then a ca
c170: 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ll to.**        
c180: 20 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f    [sqlite3_db_co
c190: 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  nfig](D,[SQLITE_
c1a0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
c1b0: 44 45 5d 2c 2e 2e 2e 29 20 73 68 61 6c 6c 0a 2a  DE],...) shall.*
c1c0: 2a 20 20 20 20 20 20 20 20 20 20 66 61 69 6c 20  *          fail 
c1d0: 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f  with an [SQLITE_
c1e0: 42 55 53 59 5d 20 72 65 74 75 72 6e 20 63 6f 64  BUSY] return cod
c1f0: 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 30 39  e..**.** {H14209
c200: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
c210: 61 6c 6c 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20  all to .**      
c220: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f      [sqlite3_db_
c230: 63 6f 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54  config](D,[SQLIT
c240: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
c250: 53 49 44 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65  SIDE],B,Z,N) whe
c260: 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44  re.**          D
c270: 20 69 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74   is an open [dat
c280: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
c290: 5d 20 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72  ] and Z and N ar
c2a0: 65 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20  e positive.**   
c2b0: 20 20 20 20 20 20 20 69 6e 74 65 67 65 72 73 20         integers 
c2c0: 61 6e 64 20 42 20 69 73 20 61 6e 20 61 6c 69 67  and B is an alig
c2d0: 6e 65 64 20 62 75 66 66 65 72 20 61 74 20 6c 65  ned buffer at le
c2e0: 61 73 74 20 5a 2a 4e 20 62 79 74 65 73 20 69 6e  ast Z*N bytes in
c2f0: 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20   size.**        
c300: 20 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68    shall cause th
c310: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  e [lookaside mem
c320: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66  ory allocator] f
c330: 6f 72 20 44 20 74 6f 20 75 73 65 20 62 75 66 66  or D to use buff
c340: 65 72 20 42 20 0a 2a 2a 20 20 20 20 20 20 20 20  er B .**        
c350: 20 20 77 69 74 68 20 4e 20 73 6c 6f 74 73 20 6f    with N slots o
c360: 66 20 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a  f Z bytes each..
c370: 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31 32 7d 20 41  **.** {H14212} A
c380: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
c390: 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   to .**         
c3a0: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
c3b0: 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44  fig](D,[SQLITE_D
c3c0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
c3d0: 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a  E],B,Z,N) where.
c3e0: 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73  **          D is
c3f0: 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61   an open [databa
c400: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
c410: 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 70  nd Z and N are p
c420: 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  ositive.**      
c430: 20 20 20 20 69 6e 74 65 67 65 72 73 20 61 6e 64      integers and
c440: 20 42 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   B is NULL point
c450: 65 72 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74  er shall cause t
c460: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
c470: 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
c480: 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20   allocator] for 
c490: 44 20 74 6f 20 61 20 6f 62 74 61 69 6e 20 5a 2a  D to a obtain Z*
c4a0: 4e 20 62 79 74 65 20 62 75 66 66 65 72 0a 2a 2a  N byte buffer.**
c4b0: 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 74            from t
c4c0: 68 65 20 70 72 69 6d 61 72 79 20 6d 65 6d 6f 72  he primary memor
c4d0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 61 6e 64 20  y allocator and 
c4e0: 75 73 65 20 74 68 61 74 20 62 75 66 66 65 72 0a  use that buffer.
c4f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68  **          with
c500: 20 4e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 6c 6f   N lookaside slo
c510: 74 73 20 6f 66 20 5a 20 62 79 74 65 73 20 65 61  ts of Z bytes ea
c520: 63 68 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31  ch..**.** {H1421
c530: 35 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  5} A successful 
c540: 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 20 20 20 20  call to .**     
c550: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 64 62       [sqlite3_db
c560: 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49  _config](D,[SQLI
c570: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
c580: 41 53 49 44 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68  ASIDE],B,Z,N) wh
c590: 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ere.**          
c5a0: 44 20 69 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61  D is an open [da
c5b0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c5c0: 6e 5d 20 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61  n] and Z and N a
c5d0: 72 65 20 7a 65 72 6f 20 73 68 61 6c 6c 0a 2a 2a  re zero shall.**
c5e0: 20 20 20 20 20 20 20 20 20 20 64 69 73 61 62 6c            disabl
c5f0: 65 20 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64 65  e the [lookaside
c600: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
c610: 72 5d 20 66 6f 72 20 44 2e 0a 2a 2a 0a 2a 2a 0a  r] for D..**.**.
c620: 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
c630: 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
c640: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
c650: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
c660: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
c670: 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
c680: 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
c690: 20 7b 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32   {H10155} <S2012
c6a0: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
c6b0: 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  AL.**.** An inst
c6c0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c6d0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
c6e0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
c6f0: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
c700: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
c710: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
c720: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
c730: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
c740: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
c750: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
c760: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
c770: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
c780: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
c790: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
c7a0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
c7b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
c7c0: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
c7d0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
c7e0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
c7f0: 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63  G_MALLOC].  By c
c800: 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
c810: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
c820: 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
c830: 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
c840: 5f 63 6f 6e 66 69 67 28 29 5d 20 64 75 72 69 6e  _config()] durin
c850: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
c860: 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69   an.** applicati
c870: 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
c880: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  n alternative me
c890: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c8a0: 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72  subsystem.** for
c8b0: 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
c8c0: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
c8d0: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
c8e0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
c8f0: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
c900: 20 77 69 74 68 20 61 20 62 75 69 6c 74 2d 69 6e   with a built-in
c910: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
c920: 72 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 72  r that is.** per
c930: 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
c940: 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
c950: 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
c960: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
c970: 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
c980: 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
c990: 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
c9a0: 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
c9b0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
c9c0: 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
c9d0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
c9e0: 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
c9f0: 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
ca00: 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
ca10: 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
ca20: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
ca30: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
ca40: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
ca50: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
ca60: 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
ca70: 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
ca80: 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
ca90: 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
caa0: 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
cab0: 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
cac0: 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
cad0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
cae0: 20 78 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c   xMalloc, xFree,
caf0: 20 61 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65   and xRealloc me
cb00: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
cb10: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
cb20: 6f 63 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e  oc(), free(), an
cb30: 64 20 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63  d realloc() func
cb40: 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
cb50: 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e  tandard library.
cb60: 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
cb70: 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
cb80: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
cb90: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
cba0: 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
cbb0: 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
cbc0: 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
cbd0: 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
cbe0: 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
cbf0: 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
cc00: 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
cc10: 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
cc20: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
cc30: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
cc40: 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
cc50: 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
cc60: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
cc70: 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
cc80: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
cc90: 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
cca0: 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
ccb0: 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
ccc0: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
ccd0: 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
cce0: 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
ccf0: 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
cd00: 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
cd10: 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
cd20: 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
cd30: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
cd40: 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
cd50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
cd60: 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
cd70: 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
cd80: 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
cd90: 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
cda0: 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
cdb0: 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
cdc0: 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
cdd0: 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
cde0: 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
cdf0: 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
ce00: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
ce10: 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
ce20: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
ce30: 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
ce40: 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
ce50: 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
ce60: 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
ce70: 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
ce80: 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
ce90: 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
cea0: 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
ceb0: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
cec0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
ced0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
cee0: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
cef0: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
cf00: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
cf10: 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
cf20: 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
cf30: 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
cf40: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
cf50: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
cf60: 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
cf70: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
cf80: 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
cf90: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
cfa0: 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
cfb0: 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
cfc0: 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
cfd0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
cfe0: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
cff0: 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
d000: 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
d010: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
d020: 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
d030: 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
d040: 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
d050: 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
d060: 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
d070: 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
d080: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
d090: 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
d0a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
d0b0: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
d0c0: 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
d0d0: 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
d0e0: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
d0f0: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
d100: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
d110: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
d120: 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
d130: 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
d140: 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
d150: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
d160: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
d170: 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30   {H10160} <S2000
d180: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
d190: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  AL.**.** These c
d1a0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
d1b0: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
d1c0: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
d1d0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
d1e0: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
d1f0: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
d200: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
d210: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
d220: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
d230: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
d240: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
d250: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
d260: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
d270: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
d280: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d290: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
d2a0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
d2b0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
d2c0: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
d2d0: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
d2e0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
d2f0: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
d300: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
d310: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
d320: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d330: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
d340: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
d350: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
d360: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
d370: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
d380: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
d390: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
d3a0: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
d3b0: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
d3c0: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
d3d0: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
d3e0: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
d3f0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
d400: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
d410: 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a  tion disables.**
d420: 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
d430: 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
d440: 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
d450: 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
d460: 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
d470: 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a  le thread.</dd>.
d480: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
d490: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
d4a0: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
d4b0: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
d4c0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
d4d0: 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74  ption.  This opt
d4e0: 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20  ion disables.** 
d4f0: 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
d500: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d510: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
d520: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
d530: 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
d540: 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
d550: 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
d560: 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
d570: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
d580: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
d590: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
d5a0: 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
d5b0: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
d5c0: 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
d5d0: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
d5e0: 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
d5f0: 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
d600: 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
d610: 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
d620: 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
d630: 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
d640: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
d650: 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
d660: 61 6d 65 20 74 69 6d 65 2e 20 20 53 65 65 20 74  ame time.  See t
d670: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
d680: 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d 65 6e 74 61  de].** documenta
d690: 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
d6a0: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
d6b0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d6c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
d6d0: 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
d6e0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
d6f0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
d700: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
d710: 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
d720: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
d730: 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
d740: 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
d750: 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
d760: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
d770: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
d780: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
d790: 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
d7a0: 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
d7b0: 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
d7c0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
d7d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
d7e0: 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
d7f0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
d800: 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
d810: 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
d820: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
d830: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
d840: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
d850: 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
d860: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
d870: 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
d880: 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
d890: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
d8a0: 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
d8b0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
d8c0: 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
d8d0: 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
d8e0: 74 69 6d 65 2e 0a 2a 2a 20 53 65 65 20 74 68 65  time..** See the
d8f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
d900: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
d910: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
d920: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e  nformation.</dd>
d930: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
d940: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c  E_CONFIG_MALLOC<
d950: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
d960: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
d970: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
d980: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
d990: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
d9a0: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
d9b0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d9c0: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
d9d0: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
d9e0: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
d9f0: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
da00: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
da10: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
da20: 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
da30: 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
da40: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
da50: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
da60: 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ite.</dd>.**.** 
da70: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
da80: 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
da90: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
daa0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
dab0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
dac0: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
dad0: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
dae0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
daf0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
db00: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
db10: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
db20: 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
db30: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
db40: 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
db50: 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
db60: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
db70: 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ..** This option
db80: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
db90: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
dba0: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
dbb0: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
dbc0: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
dbd0: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
dbe0: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
dbf0: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
dc00: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
dc10: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
dc20: 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ple.</dd>.**.** 
dc30: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
dc40: 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e  G_MEMSTATUS</dt>
dc50: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
dc60: 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
dc70: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
dc80: 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74  e int, interpret
dc90: 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c  ed as a .** bool
dca0: 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c  ean, which enabl
dcb0: 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
dcc0: 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66  he collection of
dcd0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
dce0: 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63  on .** statistic
dcf0: 73 2e 20 57 68 65 6e 20 64 69 73 61 62 6c 65 64  s. When disabled
dd00: 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
dd10: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
dd20: 73 20 62 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e  s become .** non
dd30: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
dd40: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
dd50: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
dd60: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
dd70: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
dd80: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
dd90: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
dda0: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
ddb0: 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  mit()].**   <li>
ddc0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
ddd0: 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a  ()].**   </ul>.*
dde0: 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
ddf0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
de00: 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
de10: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
de20: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
de30: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
de40: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
de50: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
de60: 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
de70: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
de80: 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
de90: 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
dea0: 2c 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  , the.** size of
deb0: 20 65 61 63 68 20 73 63 72 61 74 63 68 20 62 75   each scratch bu
dec0: 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
ded0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 75 66  he number of buf
dee0: 66 65 72 73 20 28 4e 29 2e 20 20 54 68 65 20 73  fers (N).  The s
def0: 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
df00: 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
df10: 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70   of 16. The sz p
df20: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
df30: 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a  be a few bytes.*
df40: 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  * larger than th
df50: 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 68  e actual scratch
df60: 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
df70: 64 75 65 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65  due internal ove
df80: 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69  rhead..** The fi
df90: 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rst.** argument 
dfa0: 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20  should point to 
dfb0: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66  an allocation of
dfc0: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
dfd0: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
dfe0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  ** SQLite will u
dff0: 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
e000: 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
e010: 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74  er at once per t
e020: 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73  hread, so.** N s
e030: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
e040: 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
e050: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
e060: 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a  hreads.  The sz.
e070: 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  ** parameter sho
e080: 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74  uld be 6 times t
e090: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
e0a0: 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
e0b0: 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63  page size..** Sc
e0c0: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72  ratch buffers ar
e0d0: 65 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f  e used as part o
e0e0: 66 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61  f the btree bala
e0f0: 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  nce operation.  
e100: 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20  If.** The btree 
e110: 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61  balancer needs a
e120: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79  dditional memory
e130: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
e140: 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73  provided by.** s
e150: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f  cratch buffers o
e160: 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20  r if no scratch 
e170: 62 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20  buffer space is 
e180: 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
e190: 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74  SQLite.** goes t
e1a0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
e1b0: 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74  c()] to obtain t
e1c0: 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65  he memory it nee
e1d0: 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ds.</dd>.**.** <
e1e0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
e1f0: 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
e200: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
e210: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
e220: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
e230: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
e240: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
e250: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
e260: 20 63 61 63 68 65 2e 20 20 54 68 65 72 65 20 61   cache.  There a
e270: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
e280: 74 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  ts: A pointer to
e290: 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20   the.** memory, 
e2a0: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
e2b0: 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
e2c0: 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
e2d0: 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
e2e0: 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
e2f0: 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77  nt must be a pow
e300: 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
e310: 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e  n 512 and 32768.
e320: 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
e330: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
e340: 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
e350: 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
e360: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
e370: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74  memory..** SQLit
e380: 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d  e will use the m
e390: 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62  emory provided b
e3a0: 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
e3b0: 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20  ment to satisfy 
e3c0: 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65  its.** memory ne
e3d0: 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73  eds for the firs
e3e0: 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69  t N pages that i
e3f0: 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e  t adds to cache.
e400: 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a    If additional.
e410: 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
e420: 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
e430: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
e440: 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
e450: 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
e460: 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
e470: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
e480: 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
e490: 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
e4a0: 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d  e..** The implem
e4b0: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75  entation might u
e4c0: 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  se one or more o
e4d0: 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 73 20  f the N buffers 
e4e0: 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f  to hold .** memo
e4f0: 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e  ry accounting in
e500: 66 6f 72 6d 61 74 69 6f 6e 2e 20 3c 2f 64 64 3e  formation. </dd>
e510: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
e520: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
e530: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
e540: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
e550: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
e560: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
e570: 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66  te will use.** f
e580: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
e590: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
e5a0: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65  ocation needs be
e5b0: 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
e5c0: 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53  ded.** for by [S
e5d0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
e5e0: 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATCH] and [SQLIT
e5f0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
e600: 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  HE]..** There ar
e610: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
e620: 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: A pointer to 
e630: 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  the memory, the 
e640: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
e650: 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
e660: 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
e670: 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
e680: 69 6f 6e 20 73 69 7a 65 2e 20 20 49 66 0a 2a 2a  ion size.  If.**
e690: 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
e6a0: 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
e6b0: 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
e6c0: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
e6d0: 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
e6e0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
e6f0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
e700: 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
e710: 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
e720: 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
e730: 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
e740: 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
e750: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
e760: 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
e770: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
e780: 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20  NULL and either 
e790: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
e7a0: 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53  EMSYS3] or.** [S
e7b0: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
e7c0: 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65  SYS5] are define
e7d0: 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  d, then the alte
e7e0: 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
e7f0: 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
e800: 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
e810: 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
e820: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
e830: 6e 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a  n needs.</dd>.**
e840: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
e850: 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
e860: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
e870: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
e880: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
e890: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
e8a0: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
e8b0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
e8c0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
e8d0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
e8e0: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
e8f0: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
e900: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
e910: 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
e920: 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a   used in place.*
e930: 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  * the mutex rout
e940: 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
e950: 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  SQLite.</dd>.**.
e960: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e970: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
e980: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
e990: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
e9a0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
e9b0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
e9c0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
e9d0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
e9e0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
e9f0: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
ea00: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
ea10: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
ea20: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
ea30: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
ea40: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
ea50: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  utex routines..*
ea60: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
ea70: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
ea80: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
ea90: 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
eaa0: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
eab0: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
eac0: 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
ead0: 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
eae0: 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
eaf0: 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
eb00: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64   for example.</d
eb10: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
eb20: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
eb30: 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
eb40: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
eb50: 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
eb60: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
eb70: 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d  the default.** m
eb80: 65 6d 6f 72 79 20 61 6c 6c 63 61 74 69 6f 6e 20  emory allcation 
eb90: 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d 69  lookaside optimi
eba0: 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 72  zation.  The fir
ebb0: 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
ebc0: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
ebd0: 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
ebe0: 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
ebf0: 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
ec00: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
ec10: 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
ec20: 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
ec30: 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  nection.</dd>.**
ec40: 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
ec50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
ec60: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
ec70: 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
ec80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
ec90: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
eca0: 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
ecb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
ecc0: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
ecd0: 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
ece0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
ecf0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
ed00: 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
ed10: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
ed20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ed30: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
ed40: 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
ed50: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
ed60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
ed70: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
ed80: 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
ed90: 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
eda0: 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
edb0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
edc0: 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
edd0: 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
ede0: 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
edf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
ee00: 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
ee10: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
ee20: 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
ee30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
ee40: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
ee50: 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
ee60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
ee70: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
ee80: 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
ee90: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
eea0: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
eeb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
eec0: 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
eed0: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
eee0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
eef0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
ef00: 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 20 20 31  G_CHUNKALLOC   1
ef10: 32 20 20 2f 2a 20 69 6e 74 20 74 68 72 65 73 68  2  /* int thresh
ef20: 6f 6c 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  old */.#define S
ef30: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
ef40: 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
ef50: 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a   int int */../*.
ef60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
ef70: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
ef80: 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c 53 32 30  ns {H10170} <S20
ef90: 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  000>.** EXPERIME
efa0: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  NTAL.**.** These
efb0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
efc0: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
efd0: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
efe0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
eff0: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
f000: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
f010: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
f020: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
f030: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
f040: 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
f050: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
f060: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
f070: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
f080: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
f090: 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
f0a0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
f0b0: 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
f0c0: 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
f0d0: 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
f0e0: 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
f0f0: 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
f100: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
f110: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
f120: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
f130: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
f140: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
f150: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
f160: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
f170: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
f180: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
f190: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
f1a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f1b0: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
f1c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
f1d0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
f1e0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
f1f0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
f200: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68   option takes th
f210: 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  ree additional a
f220: 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
f230: 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20  termine the .** 
f240: 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
f250: 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
f260: 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74  figuration for t
f270: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
f280: 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65  nection]..** The
f290: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
f2a0: 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
f2b0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
f2c0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
f2d0: 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
f2e0: 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
f2f0: 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
f300: 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 20 54  aside memory.  T
f310: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
f320: 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c 4c  ment may be NULL
f330: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
f340: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
f350: 61 74 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  ate the lookasid
f360: 65 0a 2a 2a 20 62 75 66 66 65 72 20 69 74 73 65  e.** buffer itse
f370: 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
f380: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
f390: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
f3a0: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
f3b0: 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
f3c0: 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
f3d0: 6e 64 20 74 68 65 20 74 68 69 72 64 20 61 72 67  nd the third arg
f3e0: 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
f3f0: 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
f400: 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
f410: 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
f420: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
f430: 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
f440: 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
f450: 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
f460: 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
f470: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
f480: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64  .</dd>.**.** </d
f490: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
f4a0: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
f4b0: 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31 20  OKASIDE    1001 
f4c0: 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
f4d0: 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t */.../*.** CAP
f4e0: 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
f4f0: 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
f500: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b  d Result Codes {
f510: 48 31 32 32 30 30 7d 20 3c 53 31 30 37 30 30 3e  H12200} <S10700>
f520: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
f530: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
f540: 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
f550: 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
f560: 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
f570: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
f580: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
f590: 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78 74   SQLite. The ext
f5a0: 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
f5b0: 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
f5c0: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
f5d0: 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
f5e0: 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69  patibility consi
f5f0: 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  derations..**.**
f600: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
f610: 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45 61 63 68  ** {H12201} Each
f620: 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63   new [database c
f630: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c 6c  onnection] shall
f640: 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20 20 20   have the.**    
f650: 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20        [extended 
f660: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
f670: 61 74 75 72 65 20 64 69 73 61 62 6c 65 64 20 62  ature disabled b
f680: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
f690: 20 7b 48 31 32 32 30 32 7d 20 54 68 65 20 5b 73   {H12202} The [s
f6a0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
f6b0: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c 46  result_codes(D,F
f6c0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
f6d0: 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 20  ll enable.**    
f6e0: 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20        [extended 
f6f0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f  result codes] fo
f700: 72 20 74 68 65 20 20 5b 64 61 74 61 62 61 73 65  r the  [database
f710: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
f720: 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68  *          if th
f730: 65 20 46 20 70 61 72 61 6d 65 74 65 72 20 69 73  e F parameter is
f740: 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62 6c   true, or disabl
f750: 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20 66  e them if F is f
f760: 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  alse..*/.int sql
f770: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
f780: 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
f790: 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
f7a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f7b0: 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
f7c0: 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c 53 31  wid {H12220} <S1
f7d0: 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68  0700>.**.** Each
f7e0: 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
f7f0: 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
f800: 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
f810: 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
f820: 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 22  key called the "
f830: 72 6f 77 69 64 22 2e 20 54 68 65 20 72 6f 77 69  rowid". The rowi
f840: 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
f850: 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
f860: 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
f870: 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
f880: 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
f890: 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
f8a0: 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
f8b0: 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
f8c0: 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
f8d0: 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20   columns. If.** 
f8e0: 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
f8f0: 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 49  column of type I
f900: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
f910: 45 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  EY then that col
f920: 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
f930: 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
f940: 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rowid..**.** Thi
f950: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
f960: 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  s the rowid of t
f970: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
f980: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
f990: 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
f9a0: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
f9b0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f9c0: 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
f9d0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
f9e0: 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66    If no successf
f9f0: 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20  ul [INSERT]s.** 
fa00: 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
fa10: 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
fa20: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
fa30: 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
fa40: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 5b 49  ..**.** If an [I
fa50: 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
fa60: 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
fa70: 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f  then the rowid o
fa80: 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
fa90: 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65  * row is returne
faa0: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
fab0: 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  e as long as the
fac0: 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e   trigger is runn
fad0: 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
fae0: 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72   the trigger ter
faf0: 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c  minates, the val
fb00: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
fb10: 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
fb20: 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61  everts to the la
fb30: 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65  st value inserte
fb40: 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  d before the tri
fb50: 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a  gger fired..**.*
fb60: 2a 20 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68  * An [INSERT] th
fb70: 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
fb80: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
fb90: 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
fba0: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
fbb0: 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
fbc0: 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
fbd0: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
fbe0: 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
fbf0: 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20 4f  .  Thus INSERT O
fc00: 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
fc10: 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
fc20: 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
fc30: 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
fc40: 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
fc50: 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
fc60: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
fc70: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
fc80: 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
fc90: 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49 4e   fails.  When IN
fca0: 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
fcb0: 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
fcc0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
fcd0: 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
fce0: 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
fcf0: 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
fd00: 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
fd10: 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
fd20: 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
fd30: 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
fd40: 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
fd50: 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
fd60: 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
fd70: 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
fd80: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
fd90: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  erface..**.** Fo
fda0: 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
fdb0: 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
fdc0: 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
fdd0: 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
fde0: 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
fdf0: 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
fe00: 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
fe10: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  back..**.** INVA
fe20: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
fe30: 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  12221} The [sqli
fe40: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
fe50: 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f  rowid()] functio
fe60: 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 74  n shall return t
fe70: 68 65 20 72 6f 77 69 64 0a 2a 2a 20 20 20 20 20  he rowid.**     
fe80: 20 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73 74       of the most
fe90: 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
fea0: 75 6c 20 5b 49 4e 53 45 52 54 5d 20 70 65 72 66  ul [INSERT] perf
feb0: 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61 6d  ormed on the sam
fec0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  e.**          [d
fed0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fee0: 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20 74  on] and within t
fef0: 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65  he same or highe
ff00: 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20 20  r level.**      
ff10: 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74      trigger cont
ff20: 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20  ext, or zero if 
ff30: 74 68 65 72 65 20 68 61 76 65 20 62 65 65 6e 20  there have been 
ff40: 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 0a 2a 2a  no qualifying.**
ff50: 20 20 20 20 20 20 20 20 20 20 5b 49 4e 53 45 52            [INSER
ff60: 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
ff70: 2a 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20 54 68  *.** {H12223} Th
ff80: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
ff90: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
ffa0: 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72  function shall r
ffb0: 65 74 75 72 6e 20 74 68 65 0a 2a 2a 20 20 20 20  eturn the.**    
ffc0: 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65        same value
ffd0: 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
ffe0: 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  m the same trigg
fff0: 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20  er context.**   
10000 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65         immediate
10010 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66  ly before and af
10020 74 65 72 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d  ter a [ROLLBACK]
10030 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
10040 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32  ONS:.**.** {A122
10050 33 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  32} If a separat
10060 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
10070 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
10080 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
10090 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
100a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
100b0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
100c0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
100d0 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  d()].**         
100e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
100f0 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
10100 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
10110 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20  nsert rowid,.** 
10120 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68           then th
10130 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
10140 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
10150 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
10160 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] is.**         
10170 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
10180 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
10190 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
101a0 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
101b0 20 20 20 20 20 20 20 20 20 6c 61 73 74 20 69 6e           last in
101c0 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73  sert rowid..*/.s
101d0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
101e0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
101f0 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
10200 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10210 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
10220 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
10230 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c 53  fied {H12240} <S
10240 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  10600>.**.** Thi
10250 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
10260 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
10270 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
10280 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
10290 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
102a0 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
102b0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
102c0 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
102d0 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
102e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
102f0 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
10300 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
10310 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c  arameter..** Onl
10320 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
10330 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
10340 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
10350 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
10360 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
10370 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
10380 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
10390 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
103a0 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
103b0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
103c0 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
103d0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
103e0 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  )] function.** t
103f0 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
10400 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
10410 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  es including cha
10420 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
10430 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41  riggers..**.** A
10440 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73   "row change" is
10450 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73   a change to a s
10460 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73  ingle row of a s
10470 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63  ingle table.** c
10480 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45  aused by an INSE
10490 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55  RT, DELETE, or U
104a0 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e  PDATE statement.
104b0 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61    Rows that.** a
104c0 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69  re changed as si
104d0 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 52 45  de effects of RE
104e0 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
104f0 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20   resolution,.** 
10500 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20  rollback, ABORT 
10510 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f 50  processing, DROP
10520 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61 6e   TABLE, or by an
10530 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
10540 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
10550 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
10560 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20   changes..**.** 
10570 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
10580 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
10590 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
105a0 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
105b0 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
105c0 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 65 72  ipt of a trigger
105d0 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  .  Most SQL stat
105e0 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
105f0 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
10600 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
10610 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
10620 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
10630 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
10640 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
10650 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
10660 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
10670 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
10680 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
10690 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
106a0 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
106b0 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
106c0 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
106d0 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
106e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  tion..**.** Call
106f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
10700 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
10710 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
10720 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
10730 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
10740 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
10750 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
10760 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
10770 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
10780 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
10790 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
107a0 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
107b0 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
107c0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
107d0 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
107e0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
107f0 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
10800 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
10810 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
10820 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
10830 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
10840 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
10850 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
10860 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
10870 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
10880 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
10890 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74 68 69  op level.  Withi
108a0 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
108b0 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20  trigger,.** the 
108c0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
108d0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
108e0 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
108f0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
10900 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
10910 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
10920 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
10930 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
10940 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
10950 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
10960 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
10970 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
10980 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
10990 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
109a0 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a  nclude changes.*
109b0 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74  * caused by subt
109c0 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68  riggers since th
109d0 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f  ose have their o
109e0 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  wn context..**.*
109f0 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65  * SQLite impleme
10a00 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20  nts the command 
10a10 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
10a20 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48  le" without a WH
10a30 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79  ERE clause.** by
10a40 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65   dropping and re
10a50 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62  creating the tab
10a60 6c 65 2e 20 20 44 6f 69 6e 67 20 73 6f 20 69 73  le.  Doing so is
10a70 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61   much faster tha
10a80 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75  n going.** throu
10a90 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20  gh and deleting 
10aa0 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65  individual eleme
10ab0 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62  nts from the tab
10ac0 6c 65 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  le.  Because of 
10ad0 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61  this.** optimiza
10ae0 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69  tion, the deleti
10af0 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46  ons in "DELETE F
10b00 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e  ROM table" are n
10b10 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61  ot row changes a
10b20 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62  nd.** will not b
10b30 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65  e counted by the
10b40 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
10b50 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74  () or [sqlite3_t
10b60 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a  otal_changes()].
10b70 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65  ** functions, re
10b80 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
10b90 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e  number of elemen
10ba0 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69  ts that were ori
10bb0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68  ginally.** in th
10bc0 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74  e table.  To get
10bd0 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
10be0 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
10bf0 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64   of rows deleted
10c00 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45  , use.** "DELETE
10c10 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52   FROM table WHER
10c20 45 20 31 22 20 69 6e 73 74 65 61 64 2e 20 20 4f  E 1" instead.  O
10c30 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e  r recompile usin
10c40 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
10c50 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f  _OMIT_TRUNCATE_O
10c60 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d  PTIMIZATION] com
10c70 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
10c80 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 0a   to disable the.
10c90 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  ** optimization 
10ca0 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a  on all queries..
10cb0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
10cc0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 31 7d  :.**.** {H12241}
10cd0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   The [sqlite3_ch
10ce0 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
10cf0 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 74  n shall return t
10d00 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
10d10 20 20 20 20 20 20 20 20 20 72 6f 77 20 63 68 61           row cha
10d20 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
10d30 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
10d40 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a  NSERT, UPDATE,.*
10d50 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 44 45  *          or DE
10d60 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 6f  LETE statement o
10d70 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
10d80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  ase connection a
10d90 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  nd.**          w
10da0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  ithin the same o
10db0 72 20 68 69 67 68 65 72 20 74 72 69 67 67 65 72  r higher trigger
10dc0 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72   context, or zer
10dd0 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65 0a  o if there have.
10de0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20  **          not 
10df0 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 66 79  been any qualify
10e00 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ing row changes.
10e10 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 33 7d 20  .**.** {H12243} 
10e20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68  Statements of th
10e30 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46  e form "DELETE F
10e40 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77  ROM tablename" w
10e50 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20  ith no.**       
10e60 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20     WHERE clause 
10e70 73 68 61 6c 6c 20 63 61 75 73 65 20 73 75 62 73  shall cause subs
10e80 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
10e90 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
10ea0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
10eb0 74 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f 2c 20  to return zero, 
10ec0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
10ed0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
10ee0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6f 72 69  mber of rows ori
10ef0 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 20 74  ginally in the t
10f00 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  able..**.** ASSU
10f10 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
10f20 41 31 32 32 35 32 7d 20 49 66 20 61 20 73 65 70  A12252} If a sep
10f30 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
10f40 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
10f50 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
10f60 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
10f70 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71         while [sq
10f80 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
10f90 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
10fa0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
10fb0 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
10fc0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
10fd0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
10fe0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
10ff0 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
11000 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
11010 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
11020 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
11030 69 66 69 65 64 20 7b 48 31 32 32 36 30 7d 20 3c  ified {H12260} <
11040 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10600>.**.** Th
11050 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
11060 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
11070 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
11080 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 0a  used by INSERT,.
11090 2a 2a 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  ** UPDATE or DEL
110a0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73  ETE statements s
110b0 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
110c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
110d0 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68  as opened..** Th
110e0 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73  e count includes
110f0 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f   all changes fro
11100 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 20 63 6f  m all trigger co
11110 6e 74 65 78 74 73 2e 20 20 48 6f 77 65 76 65 72  ntexts.  However
11120 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64  ,.** the count d
11130 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
11140 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20  changes used to 
11150 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43  implement REPLAC
11160 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  E constraints,.*
11170 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
11180 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
11190 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74 61 62 6c  ng, or DROP tabl
111a0 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a  e processing..**
111b0 20 54 68 65 20 63 68 61 6e 67 65 73 20 61 72 65   The changes are
111c0 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e   counted as soon
111d0 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
111e0 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  t that makes the
111f0 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  m is.** complete
11200 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
11210 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20  ement handle is 
11220 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
11230 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
11240 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
11250 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
11260 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
11270 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45   the command "DE
11280 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
11290 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45   without a WHERE
112a0 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72   clause.** by dr
112b0 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65  opping and recre
112c0 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e  ating the table.
112d0 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20    (This is much 
112e0 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e  faster than goin
112f0 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64  g.** through and
11300 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69   deleting indivi
11310 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72  dual elements fr
11320 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20  om the table.)  
11330 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a  Because of this.
11340 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c  ** optimization,
11350 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69   the deletions i
11360 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  n "DELETE FROM t
11370 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f  able" are not ro
11380 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a  w changes and.**
11390 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75   will not be cou
113a0 6e 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  nted by the sqli
113b0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72  te3_changes() or
113c0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
113d0 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75  changes()].** fu
113e0 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c  nctions, regardl
113f0 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ess of the numbe
11400 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68  r of elements th
11410 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c  at were original
11420 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62  ly.** in the tab
11430 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61  le.  To get an a
11440 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66  ccurate count of
11450 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
11460 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65  ows deleted, use
11470 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  .** "DELETE FROM
11480 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20   table WHERE 1" 
11490 69 6e 73 74 65 61 64 2e 20 20 20 4f 72 20 72 65  instead.   Or re
114a0 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67 20 74 68  compile using th
114b0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  e.** [SQLITE_OMI
114c0 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50 54 49 4d  T_TRUNCATE_OPTIM
114d0 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70 69 6c 65  IZATION] compile
114e0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 6f 20  -time option to 
114f0 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 6f  disable the.** o
11500 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f 6e 20 61  ptimization on a
11510 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  ll queries..**.*
11520 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
11530 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
11540 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
11550 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
11560 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 31 7d 20 54  **.** {H12261} T
11570 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
11580 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74  l_changes()] ret
11590 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
115a0 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  umber.**        
115b0 20 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73    of row changes
115c0 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52   caused by INSER
115d0 54 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f  T, UPDATE, and/o
115e0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20  r DELETE.**     
115f0 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20       statements 
11600 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
11610 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11620 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20  ], in any.**    
11630 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f        trigger co
11640 6e 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65  ntext, since the
11650 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11660 74 69 6f 6e 20 77 61 73 20 63 72 65 61 74 65 64  tion was created
11670 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 33 7d  ..**.** {H12263}
11680 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74   Statements of t
11690 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20  he form "DELETE 
116a0 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20  FROM tablename" 
116b0 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20  with no.**      
116c0 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65      WHERE clause
116d0 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e 67   shall not chang
116e0 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
116f0 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
11700 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74   by [sqlite3_tot
11710 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a 2a  al_changes()]..*
11720 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
11730 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 36 34 7d  :.**.** {A12264}
11740 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
11750 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
11760 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
11770 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11780 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
11790 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
117a0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
117b0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
117c0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  the value.**    
117d0 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 69        returned i
117e0 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
117f0 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
11800 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
11810 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
11820 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
11830 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
11840 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
11850 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32  nning Query {H12
11860 32 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a  270} <S30500>.**
11870 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
11880 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
11890 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
118a0 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
118b0 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
118c0 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
118d0 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
118e0 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
118f0 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
11900 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
11910 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
11920 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
11930 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
11940 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
11950 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
11960 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
11970 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
11980 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  iately..**.** It
11990 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
119a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
119b0 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
119c0 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
119d0 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
119e0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
119f0 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
11a00 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
11a10 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
11a20 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
11a30 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
11a40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11a50 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
11a60 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
11a70 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
11a80 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
11a90 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
11aa0 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
11ab0 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
11ac0 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
11ad0 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
11ae0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
11af0 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
11b00 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
11b10 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
11b20 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
11b30 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
11b40 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
11b50 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
11b60 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   An SQL operatio
11b70 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
11b80 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
11b90 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
11ba0 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  UPT]..** If the 
11bb0 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
11bc0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
11bd0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
11be0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
11bf0 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
11c00 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
11c10 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
11c20 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
11c30 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
11c40 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
11c50 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  cally..**.** A c
11c60 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
11c70 6e 74 65 72 72 75 70 74 28 29 20 68 61 73 20 6e  nterrupt() has n
11c80 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
11c90 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
11ca0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
11cb0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74  fter sqlite3_int
11cc0 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
11cd0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
11ce0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37  TS:.**.** {H1227
11cf0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
11d00 69 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e 74  interrupt()] int
11d10 65 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72 63  erface will forc
11d20 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a  e all running.**
11d30 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74            SQL st
11d40 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
11d50 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d  ted with the sam
11d60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
11d70 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
11d80 20 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72 20    to halt after 
11d90 70 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d 6f  processing at mo
11da0 73 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e 61  st one additiona
11db0 6c 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  l row of data..*
11dc0 2a 0a 2a 2a 20 7b 48 31 32 32 37 32 7d 20 41 6e  *.** {H12272} An
11dd0 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
11de0 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
11df0 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
11e00 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
11e10 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65           will re
11e20 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
11e30 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41  ERRUPT]..**.** A
11e40 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
11e50 2a 20 7b 41 31 32 32 37 39 7d 20 49 66 20 74 68  * {A12279} If th
11e60 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
11e70 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
11e80 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
11e90 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20  rrupt()].**     
11ea0 20 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67 20       is running 
11eb0 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
11ec0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
11ed0 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  en..*/.void sqli
11ee0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
11ef0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
11f00 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
11f10 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
11f20 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
11f30 65 74 65 20 7b 48 31 30 35 31 30 7d 20 3c 53 37  ete {H10510} <S7
11f40 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0200>.**.** Thes
11f50 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
11f60 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e  seful for comman
11f70 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
11f80 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
11f90 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
11fa0 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
11fb0 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74   to form complet
11fc0 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  e a SQL statemen
11fd0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
11fe0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
11ff0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
12000 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
12010 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
12020 20 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65   parsing.  These
12030 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
12040 20 74 72 75 65 20 69 66 20 74 68 65 20 69 6e 70   true if the inp
12050 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
12060 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
12070 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
12080 65 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e  ent.  A statemen
12090 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
120a0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
120b0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
120c0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
120d0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61  and is not a fra
120e0 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52  gment of a.** CR
120f0 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
12100 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c  tement.  Semicol
12110 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
12120 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
12130 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
12140 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
12150 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
12160 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
12170 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
12180 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
12190 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
121a0 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
121b0 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
121c0 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
121d0 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
121e0 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
121f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
12200 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
12210 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
12220 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
12230 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
12240 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
12250 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
12260 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
12270 2a 2a 20 7b 48 31 30 35 31 31 7d 20 41 20 73 75  ** {H10511} A su
12280 63 63 65 73 73 66 75 6c 20 65 76 61 6c 75 61 74  ccessful evaluat
12290 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
122a0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 0a 2a  complete()] or.*
122b0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
122c0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
122d0 5d 20 66 75 6e 63 74 69 6f 6e 73 20 73 68 61 6c  ] functions shal
122e0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  l.**          re
122f0 74 75 72 6e 20 61 20 6e 75 6d 65 72 69 63 20 31  turn a numeric 1
12300 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
12310 74 68 65 20 6c 61 73 74 20 6e 6f 6e 2d 77 68 69  the last non-whi
12320 74 65 73 70 61 63 65 0a 2a 2a 20 20 20 20 20 20  tespace.**      
12330 20 20 20 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65      token in the
12340 69 72 20 69 6e 70 75 74 20 69 73 20 61 20 73 65  ir input is a se
12350 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 20 69 73 20  micolon that is 
12360 6e 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  not in between.*
12370 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 42  *          the B
12380 45 47 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20  EGIN and END of 
12390 61 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  a CREATE TRIGGER
123a0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
123b0 2a 20 7b 48 31 30 35 31 32 7d 20 49 66 20 61 20  * {H10512} If a 
123c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
123d0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
123e0 75 72 69 6e 67 20 61 6e 20 69 6e 76 6f 63 61 74  uring an invocat
123f0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
12400 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  of [sqlite3_comp
12410 6c 65 74 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lete()] or [sqli
12420 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
12430 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20  ] then the.**   
12440 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73         routine s
12450 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  hall return [SQL
12460 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
12470 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
12480 2a 0a 2a 2a 20 7b 41 31 30 35 31 32 7d 20 54 68  *.** {A10512} Th
12490 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
124a0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
124b0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
124c0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20  erminated.**    
124d0 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69        UTF-8 stri
124e0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31  ng..**.** {A1051
124f0 33 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  3} The input to 
12500 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
12510 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
12520 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
12530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46  .**          UTF
12540 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
12550 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
12560 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12570 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
12580 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
12590 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
125a0 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
125b0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
125c0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
125d0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
125e0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
125f0 72 72 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c  rrors {H12310} <
12600 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40400>.**.** Th
12610 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
12620 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
12630 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62  ion that might b
12640 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
12650 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
12660 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
12670 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
12680 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  e that another t
12690 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
126a0 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a  ess has locked..
126b0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73  **.** If the bus
126c0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
126d0 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
126e0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
126f0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
12700 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
12710 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
12720 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
12730 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62  e lock. If the b
12740 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
12750 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
12760 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  n the callback w
12770 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ill be invoked w
12780 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
12790 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
127a0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
127b0 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  he handler is a 
127c0 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
127d0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
127e0 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
127f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
12800 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
12810 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
12820 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
12830 68 65 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  he handler callb
12840 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
12850 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
12860 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
12870 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
12880 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f  oked for this lo
12890 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66  cking event.  If
128a0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
128b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
128c0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
128d0 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
128e0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
128f0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
12900 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
12910 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
12920 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
12930 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74  eturned..** If t
12940 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
12950 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
12960 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
12970 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
12980 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
12990 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
129a0 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
129b0 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
129c0 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
129d0 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
129e0 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
129f0 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
12a00 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
12a10 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
12a20 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74  ention. If SQLit
12a30 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
12a40 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
12a50 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
12a60 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
12a70 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
12a80 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
12a90 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
12aa0 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
12ab0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
12ac0 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
12ad0 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
12ae0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
12af0 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
12b00 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
12b10 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
12b20 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
12b30 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
12b40 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
12b50 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
12b60 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
12b70 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
12b80 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
12b90 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
12ba0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
12bb0 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
12bc0 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
12bd0 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
12be0 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
12bf0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
12c00 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
12c10 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
12c20 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
12c30 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
12c40 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
12c50 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
12c60 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
12c70 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
12c80 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
12c90 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
12ca0 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
12cb0 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
12cc0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
12cd0 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
12ce0 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
12cf0 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
12d00 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
12d10 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
12d20 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
12d30 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
12d40 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
12d50 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
12d60 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  ed..**.** The de
12d70 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
12d80 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
12d90 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42  ** The [SQLITE_B
12da0 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f  USY] error is co
12db0 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49  nverted to [SQLI
12dc0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
12dd0 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  ].** when SQLite
12de0 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c   is in the middl
12df0 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61  e of a large tra
12e00 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61  nsaction where a
12e10 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65  ll the.** change
12e20 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69  s will not fit i
12e30 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  nto the in-memor
12e40 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65  y cache.  SQLite
12e50 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79   will.** already
12e60 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44   hold a RESERVED
12e70 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74   lock on the dat
12e80 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20  abase file, but 
12e90 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70  it needs.** to p
12ea0 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b  romote this lock
12eb0 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f   to EXCLUSIVE so
12ec0 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69   that it can spi
12ed0 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65  ll cache.** page
12ee0 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  s into the datab
12ef0 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74  ase file without
12f00 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72   harm to concurr
12f10 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20  ent.** readers. 
12f20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65   If it is unable
12f30 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
12f40 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
12f50 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
12f60 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
12f70 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
12f80 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
12f90 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
12fa0 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
12fb0 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
12fc0 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
12fd0 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
12fe0 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
12ff0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
13000 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20  D].  This error 
13010 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
13020 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
13030 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
13040 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
13050 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
13060 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
13070 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
13080 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
13090 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
130a0 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
130b0 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
130c0 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
130d0 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
130e0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
130f0 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f  *.** There can o
13100 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
13110 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
13120 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
13130 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13140 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
13150 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
13160 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
13170 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
13180 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20   handler.  Note 
13190 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
131a0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
131b0 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ut()].** will al
131c0 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20  so set or clear 
131d0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
131e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
131f0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
13200 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
13210 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
13220 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
13230 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
13240 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
13250 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e  usy handler.  An
13260 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
13270 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
13280 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
13290 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  ** .** INVARIANT
132a0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 31  S:.**.** {H12311
132b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
132c0 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 43 2c  usy_handler(D,C,
132d0 41 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61  A)] function sha
132e0 6c 6c 20 72 65 70 6c 61 63 65 0a 2a 2a 20 20 20  ll replace.**   
132f0 20 20 20 20 20 20 20 62 75 73 79 20 63 61 6c 6c         busy call
13300 62 61 63 6b 20 69 6e 20 74 68 65 20 5b 64 61 74  back in the [dat
13310 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13320 5d 20 44 20 77 69 74 68 20 61 20 6e 65 77 0a 2a  ] D with a new.*
13330 2a 20 20 20 20 20 20 20 20 20 20 61 20 6e 65 77  *          a new
13340 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 43 20   busy handler C 
13350 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  and application 
13360 64 61 74 61 20 70 6f 69 6e 74 65 72 20 41 2e 0a  data pointer A..
13370 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 32 7d 20 4e  **.** {H12312} N
13380 65 77 6c 79 20 63 72 65 61 74 65 64 20 5b 64 61  ewly created [da
13390 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
133a0 6e 73 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 61  ns] shall have a
133b0 20 62 75 73 79 0a 2a 2a 20 20 20 20 20 20 20 20   busy.**        
133c0 20 20 68 61 6e 64 6c 65 72 20 6f 66 20 4e 55 4c    handler of NUL
133d0 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 34  L..**.** {H12314
133e0 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f  } When two or mo
133f0 72 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  re [database con
13400 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61 72 65 20  nections] share 
13410 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  a.**          [s
13420 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
13430 61 72 65 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d  ared_cache | com
13440 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20  mon cache],.**  
13450 20 20 20 20 20 20 20 20 74 68 65 20 62 75 73 79          the busy
13460 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65   handler for the
13470 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13480 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75  tion currently u
13490 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
134a0 20 74 68 65 20 63 61 63 68 65 20 73 68 61 6c 6c   the cache shall
134b0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
134c0 20 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f 75   the cache encou
134d0 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a  nters a lock..**
134e0 0a 2a 2a 20 7b 48 31 32 33 31 36 7d 20 49 66 20  .** {H12316} If 
134f0 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  a busy handler c
13500 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
13510 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 53  zero, then the S
13520 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
13530 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
13540 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f   provoked the lo
13550 63 6b 69 6e 67 20 65 76 65 6e 74 20 73 68 61 6c  cking event shal
13560 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
13570 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _BUSY]..**.** {H
13580 31 32 33 31 38 7d 20 53 51 4c 69 74 65 20 73 68  12318} SQLite sh
13590 61 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  all invokes the 
135a0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74  busy handler wit
135b0 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  h two arguments 
135c0 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20  which.**        
135d0 20 20 61 72 65 20 61 20 63 6f 70 79 20 6f 66 20    are a copy of 
135e0 74 68 65 20 70 6f 69 6e 74 65 72 20 73 75 70 70  the pointer supp
135f0 6c 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20  lied by the 3rd 
13600 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
13610 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
13620 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
13630 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66  ] and a count of
13640 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
13650 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rior.**         
13660 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
13670 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
13680 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f   for the same lo
13690 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a  cking event..**.
136a0 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
136b0 2a 2a 0a 2a 2a 20 7b 41 31 32 33 31 39 7d 20 41  **.** {A12319} A
136c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
136d0 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
136e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
136f0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
13700 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
13710 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
13720 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
13730 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
13740 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
13750 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
13760 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
13770 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
13780 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
13790 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31  Busy Timeout {H1
137a0 32 33 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a  2340} <S40410>.*
137b0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
137c0 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
137d0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
137e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
137f0 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
13800 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
13810 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
13820 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
13830 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65  ked.  The handle
13840 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
13850 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
13860 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
13870 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
13880 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
13890 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
138a0 20 7b 48 31 32 33 34 33 7d 20 41 66 74 65 72 20   {H12343} After 
138b0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
138c0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
138d0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
138e0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
138f0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
13900 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
13910 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
13920 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
13930 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
13940 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  * Calling this r
13950 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
13960 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
13970 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
13980 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
13990 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
139a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63  s..**.** There c
139b0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
139c0 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
139d0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
139e0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
139f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
13a00 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
13a10 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
13a20 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
13a30 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
13a40 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
13a50 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
13a60 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
13a70 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
13a80 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
13a90 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
13aa0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
13ab0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 31  S:.**.** {H12341
13ac0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
13ad0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66  usy_timeout()] f
13ae0 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 6f 76  unction shall ov
13af0 65 72 72 69 64 65 20 61 6e 79 20 70 72 69 6f 72  erride any prior
13b00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
13b10 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
13b20 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ut()] or [sqlite
13b30 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
13b40 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  ] setting.**    
13b50 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d        on the sam
13b60 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
13b70 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ection]..**.** {
13b80 48 31 32 33 34 33 7d 20 49 66 20 74 68 65 20 32  H12343} If the 2
13b90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
13ba0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
13bb0 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c 65 73 73  meout()] is less
13bc0 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20   than.**        
13bd0 20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65    or equal to ze
13be0 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 62 75 73  ro, then the bus
13bf0 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20  y handler shall 
13c00 62 65 20 63 6c 65 61 72 65 64 20 73 6f 20 74 68  be cleared so th
13c10 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  at.**          a
13c20 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6c 6f  ll subsequent lo
13c30 63 6b 69 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d  cking events imm
13c40 65 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20  ediately return 
13c50 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
13c60 2a 0a 2a 2a 20 7b 48 31 32 33 34 34 7d 20 49 66  *.** {H12344} If
13c70 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
13c80 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
13c90 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69  usy_timeout()] i
13ca0 73 20 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20  s a positive.** 
13cb0 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
13cc0 4e 2c 20 74 68 65 6e 20 61 20 62 75 73 79 20 68  N, then a busy h
13cd0 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20  andler shall be 
13ce0 73 65 74 20 74 68 61 74 20 72 65 70 65 61 74 65  set that repeate
13cf0 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20  dly calls.**    
13d00 20 20 20 20 20 20 74 68 65 20 78 53 6c 65 65 70        the xSleep
13d10 28 29 20 6d 65 74 68 6f 64 20 69 6e 20 74 68 65  () method in the
13d20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
13d30 56 46 53 20 69 6e 74 65 72 66 61 63 65 5d 20 75  VFS interface] u
13d40 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntil.**         
13d50 20 65 69 74 68 65 72 20 74 68 65 20 6c 6f 63 6b   either the lock
13d60 20 63 6c 65 61 72 73 20 6f 72 20 75 6e 74 69 6c   clears or until
13d70 20 74 68 65 20 63 75 6d 75 6c 61 74 69 76 65 20   the cumulative 
13d80 73 6c 65 65 70 20 74 69 6d 65 0a 2a 2a 20 20 20  sleep time.**   
13d90 20 20 20 20 20 20 20 72 65 70 6f 72 74 65 64 20         reported 
13da0 62 61 63 6b 20 62 79 20 78 53 6c 65 65 70 28 29  back by xSleep()
13db0 20 65 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69   exceeds N milli
13dc0 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20  seconds..*/.int 
13dd0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
13de0 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
13df0 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
13e00 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
13e10 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
13e20 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
13e30 73 20 7b 48 31 32 33 37 30 7d 20 3c 53 31 30 30  s {H12370} <S100
13e40 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  00>.**.** Defini
13e50 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
13e60 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
13e70 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
13e80 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
13e90 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
13ea0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
13eb0 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
13ec0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
13ed0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
13ee0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
13ef0 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
13f00 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
13f10 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
13f20 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
13f30 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
13f40 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
13f50 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
13f60 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
13f70 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
13f80 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
13f90 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
13fa0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
13fb0 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
13fc0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
13fd0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
13fe0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
13ff0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
14000 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
14010 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
14020 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
14030 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
14040 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
14050 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
14060 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
14070 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
14080 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
14090 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
140a0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
140b0 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
140c0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
140d0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
140e0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
140f0 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
14100 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
14110 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
14120 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
14130 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
14140 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
14150 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
14160 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
14170 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
14180 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
14190 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
141a0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
141b0 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
141c0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
141d0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
141e0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
141f0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
14200 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
14210 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
14220 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
14230 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
14240 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
14250 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
14260 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
14270 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e  ()]..**.** As an
14280 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
14290 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
142a0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
142b0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
142c0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
142d0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
142e0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
142f0 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
14300 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
14310 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14320 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
14330 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
14340 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
14350 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
14360 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
14370 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
14380 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
14390 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
143a0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
143b0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
143c0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
143d0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
143e0 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
143f0 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
14400 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
14410 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
14420 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
14430 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
14440 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
14450 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
14460 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
14470 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
14480 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
14490 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
144a0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
144b0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
144c0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
144d0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
144e0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
144f0 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
14500 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
14510 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
14520 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
14530 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
14540 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
14550 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
14560 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
14570 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
14580 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
14590 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
145a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
145b0 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
145c0 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
145d0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
145e0 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
145f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
14600 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
14610 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
14620 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
14630 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74  d parameter.  It
14640 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
14650 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
14660 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
14670 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
14680 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
14690 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  r the calling fu
146a0 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  nction has finis
146b0 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65  hed using the re
146c0 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a  sult, it should.
146d0 2a 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  ** pass the poin
146e0 74 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c  ter to the resul
146f0 74 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74  t table to sqlit
14700 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
14710 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
14720 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
14730 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
14740 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
14750 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
14760 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14770 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
14780 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
14790 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
147a0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
147b0 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
147c0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
147d0 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
147e0 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
147f0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
14800 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
14810 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
14820 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
14830 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
14840 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
14850 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
14860 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
14870 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
14880 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
14890 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
148a0 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
148b0 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
148c0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
148d0 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
148e0 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
148f0 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
14900 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
14910 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
14920 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
14930 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
14940 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
14950 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
14960 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
14970 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
14980 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
14990 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
149a0 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
149b0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
149c0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
149d0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
149e0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a  _errmsg()]..**.*
149f0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
14a00 0a 2a 2a 20 7b 48 31 32 33 37 31 7d 20 49 66 20  .** {H12371} If 
14a10 61 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  a [sqlite3_get_t
14a20 61 62 6c 65 28 29 5d 20 66 61 69 6c 73 20 61 20  able()] fails a 
14a30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14a40 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  n, then.**      
14a50 20 20 20 20 69 74 20 73 68 61 6c 6c 20 66 72 65      it shall fre
14a60 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
14a70 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75  le under constru
14a80 63 74 69 6f 6e 2c 20 61 62 6f 72 74 20 74 68 65  ction, abort the
14a90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75 65  .**          que
14aa0 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20 73  ry in process, s
14ab0 6b 69 70 20 61 6e 79 20 73 75 62 73 65 71 75 65  kip any subseque
14ac0 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65 74 20  nt queries, set 
14ad0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
14ae0 2a 70 61 7a 52 65 73 75 6c 74 20 6f 75 74 70 75  *pazResult outpu
14af0 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c  t pointer to NUL
14b00 4c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  L and return [SQ
14b10 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
14b20 2a 2a 20 7b 48 31 32 33 37 33 7d 20 49 66 20 74  ** {H12373} If t
14b30 68 65 20 70 6e 43 6f 6c 75 6d 6e 20 70 61 72 61  he pnColumn para
14b40 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
14b50 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
14b60 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20  s not NULL.**   
14b70 20 20 20 20 20 20 20 74 68 65 6e 20 61 20 73 75         then a su
14b80 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
14b90 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
14ba0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73 68 61  get_table()] sha
14bb0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ll.**          w
14bc0 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20  rite the number 
14bd0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
14be0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
14bf0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20  sult set of the 
14c00 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 43 6f  query into *pnCo
14c10 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  lumn..**.** {H12
14c20 33 37 34 7d 20 49 66 20 74 68 65 20 70 6e 52 6f  374} If the pnRo
14c30 77 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  w parameter to [
14c40 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
14c50 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  e()] is not NULL
14c60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
14c70 6e 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69  n a successful i
14c80 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
14c90 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14ca0 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20  )] shall.**     
14cb0 20 20 20 20 20 77 72 69 74 65 73 20 74 68 65 20       writes the 
14cc0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69  number of rows i
14cd0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
14ce0 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
14cf0 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a  the query into *
14d00 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  pnRow..**.** {H1
14d10 32 33 37 36 7d 20 41 20 73 75 63 63 65 73 73 66  2376} A successf
14d20 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
14d30 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
14d40 62 6c 65 28 29 5d 20 74 68 61 74 20 63 6f 6d 70  ble()] that comp
14d50 75 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  utes.**         
14d60 20 4e 20 72 6f 77 73 20 6f 66 20 72 65 73 75 6c   N rows of resul
14d70 74 20 77 69 74 68 20 43 20 63 6f 6c 75 6d 6e 73  t with C columns
14d80 20 70 65 72 20 72 6f 77 20 73 68 61 6c 6c 20 6d   per row shall m
14d90 61 6b 65 20 2a 70 61 7a 52 65 73 75 6c 74 0a 2a  ake *pazResult.*
14da0 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
14db0 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
14dc0 70 6f 69 6e 74 65 72 73 20 74 6f 20 28 4e 2b 31  pointers to (N+1
14dd0 29 2a 43 20 73 74 72 69 6e 67 73 20 77 68 65 72  )*C strings wher
14de0 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 20  e the first.**  
14df0 20 20 20 20 20 20 20 20 43 20 73 74 72 69 6e 67          C string
14e00 73 20 61 72 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  s are column nam
14e10 65 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66  es as obtained f
14e20 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rom.**          
14e30 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
14e40 6e 61 6d 65 28 29 5d 20 61 6e 64 20 74 68 65 20  name()] and the 
14e50 72 65 73 74 20 61 72 65 20 63 6f 6c 75 6d 6e 20  rest are column 
14e60 72 65 73 75 6c 74 20 76 61 6c 75 65 73 0a 2a 2a  result values.**
14e70 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e            obtain
14e80 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
14e90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
14ea0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 39 7d 20  .**.** {H12379} 
14eb0 54 68 65 20 76 61 6c 75 65 73 20 69 6e 20 74 68  The values in th
14ec0 65 20 70 61 7a 52 65 73 75 6c 74 20 61 72 72 61  e pazResult arra
14ed0 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  y returned by [s
14ee0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14ef0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
14f00 73 68 61 6c 6c 20 72 65 6d 61 69 6e 20 76 61 6c  shall remain val
14f10 69 64 20 75 6e 74 69 6c 20 63 6c 65 61 72 65 64  id until cleared
14f20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
14f30 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
14f40 2a 20 7b 48 31 32 33 38 32 7d 20 57 68 65 6e 20  * {H12382} When 
14f50 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
14f60 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f  during evaluatio
14f70 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65  n of [sqlite3_ge
14f80 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20  t_table()].**   
14f90 20 20 20 20 20 20 20 74 68 65 20 66 75 6e 63 74         the funct
14fa0 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 2a 70  ion shall set *p
14fb0 61 7a 52 65 73 75 6c 74 20 74 6f 20 4e 55 4c 4c  azResult to NULL
14fc0 2c 20 77 72 69 74 65 20 61 6e 20 65 72 72 6f 72  , write an error
14fd0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20   message.**     
14fe0 20 20 20 20 20 69 6e 74 6f 20 6d 65 6d 6f 72 79       into memory
14ff0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
15000 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15010 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 20 20 20 20 20  ], make.**      
15020 20 20 20 20 2a 2a 70 7a 45 72 72 6d 73 67 20 70      **pzErrmsg p
15030 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 65 72 72  oint to that err
15040 6f 72 20 6d 65 73 73 61 67 65 2c 20 61 6e 64 20  or message, and 
15050 72 65 74 75 72 6e 20 61 0a 2a 2a 20 20 20 20 20  return a.**     
15060 20 20 20 20 20 61 70 70 72 6f 70 72 69 61 74 65       appropriate
15070 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
15080 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
15090 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
150a0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
150b0 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
150c0 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
150d0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
150e0 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
150f0 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
15100 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
15110 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
15120 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
15130 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
15140 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
15150 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
15160 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
15170 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
15180 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
15190 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
151a0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
151b0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
151c0 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
151d0 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
151e0 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
151f0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
15200 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
15210 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
15220 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
15230 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
15240 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20  ctions {H17400} 
15250 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30 3e  <S70000><S20000>
15260 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
15270 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c  tines are workal
15280 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
15290 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
152a0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
152b0 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
152c0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
152d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72   The sqlite3_mpr
152e0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
152f0 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
15300 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
15310 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
15320 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
15330 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
15340 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
15350 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
15360 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
15370 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
15380 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
15390 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
153a0 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69  ()].  Both routi
153b0 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
153c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
153d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
153e0 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
153f0 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
15400 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
15410 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
15420 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e  string..**.** In
15430 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
15440 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
15450 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
15460 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
15470 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
15480 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
15490 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
154a0 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
154b0 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
154c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
154d0 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
154e0 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
154f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
15500 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
15510 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
15520 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
15530 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
15540 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
15550 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
15560 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
15570 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
15580 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
15590 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
155a0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
155b0 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f  lity.  Note also
155c0 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
155d0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
155e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
155f0 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
15600 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
15610 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
15620 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
15630 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
15640 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74  fer.  We admit t
15650 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
15660 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
15670 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
15680 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
15690 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
156a0 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
156b0 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
156c0 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
156d0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
156e0 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
156f0 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
15700 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e  ty..**.** As lon
15710 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
15720 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
15730 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
15740 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
15750 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
15760 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
15770 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
15780 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73  nated.  The firs
15790 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
157a0 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
157b0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
157c0 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
157d0 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
157e0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
157f0 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
15800 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
15810 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
15820 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
15830 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
15840 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
15850 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
15860 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
15870 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
15880 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
15890 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
158a0 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
158b0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
158c0 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
158d0 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
158e0 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
158f0 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
15900 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
15910 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
15920 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
15930 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f  .** The %q optio
15940 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
15950 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
15960 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65  itutes a null-te
15970 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
15980 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
15990 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
159a0 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
159b0 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
159c0 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
159d0 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
159e0 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
159f0 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75  literal.  By dou
15a00 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
15a10 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
15a20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
15a30 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
15a40 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
15a50 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
15a60 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
15a70 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
15a80 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
15a90 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
15aa0 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
15ab0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
15ac0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
15ad0 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
15ae0 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
15af0 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
15b00 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
15b10 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
15b20 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
15b30 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
15b40 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
15b50 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
15b60 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
15b70 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
15b80 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
15b90 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
15ba0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
15bb0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
15bc0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
15bd0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
15be0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
15bf0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
15c00 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
15c10 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
15c20 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
15c30 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
15c40 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
15c50 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
15c60 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
15c70 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
15c80 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
15c90 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
15ca0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
15cb0 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
15cc0 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
15cd0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
15ce0 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
15cf0 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
15d00 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
15d10 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
15d20 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
15d30 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
15d40 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
15d50 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
15d60 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
15d70 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
15d80 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
15d90 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
15da0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
15db0 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
15dc0 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
15dd0 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
15de0 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
15df0 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
15e00 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
15e10 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
15e20 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
15e30 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
15e40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f  ..**.** The %Q o
15e50 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
15e60 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
15e70 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
15e80 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
15e90 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
15ea0 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
15eb0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
15ec0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
15ed0 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
15ee0 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
15ef0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
15f00 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
15f10 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
15f20 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
15f30 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f  otes) in place o
15f40 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e  f the %Q option.
15f50 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
15f60 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
15f70 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
15f80 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
15f90 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
15fa0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
15fb0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
15fc0 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
15fd0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
15fe0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
15ff0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
16000 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
16010 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
16020 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
16030 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
16040 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
16050 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
16060 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
16070 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
16080 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
16090 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
160a0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
160b0 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
160c0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61  option works exa
160d0 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77  ctly like "%s" w
160e0 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
160f0 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
16100 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
16110 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
16120 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
16130 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
16140 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
16150 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
16160 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  tring. {END}.**.
16170 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
16180 2a 0a 2a 2a 20 7b 48 31 37 34 30 33 7d 20 20 54  *.** {H17403}  T
16190 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  he [sqlite3_mpri
161a0 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ntf()] and [sqli
161b0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20  te3_vmprintf()] 
161c0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20 20  interfaces.**   
161d0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 65          return e
161e0 69 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20 74  ither pointers t
161f0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
16200 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20  d UTF-8 strings 
16210 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20  held in.**      
16220 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61       memory obta
16230 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
16240 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
16250 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69 66  NULL pointers if
16260 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20  .**           a 
16270 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
16280 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73  _malloc()] fails
16290 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 36 7d  ..**.** {H17406}
162a0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73    The [sqlite3_s
162b0 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72  nprintf()] inter
162c0 66 61 63 65 20 77 72 69 74 65 73 20 61 20 7a 65  face writes a ze
162d0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
162e0 20 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38             UTF-8
162f0 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65   string into the
16300 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20   buffer pointed 
16310 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
16320 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
16330 20 20 20 20 20 20 20 20 70 72 6f 76 69 64 65 64          provided
16340 20 74 68 61 74 20 74 68 65 20 66 69 72 73 74 20   that the first 
16350 70 61 72 61 6d 65 74 65 72 20 69 73 20 67 72 65  parameter is gre
16360 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a  ater than zero..
16370 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 37 7d 20 20  **.** {H17407}  
16380 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  The [sqlite3_snp
16390 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61  rintf()] interfa
163a0 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74  ce does not writ
163b0 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20  e slots of.**   
163c0 20 20 20 20 20 20 20 20 69 74 73 20 6f 75 74 70          its outp
163d0 75 74 20 62 75 66 66 65 72 20 28 74 68 65 20 73  ut buffer (the s
163e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 29  econd parameter)
163f0 20 6f 75 74 73 69 64 65 20 74 68 65 20 72 61 6e   outside the ran
16400 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ge.**           
16410 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d 31  of 0 through N-1
16420 20 28 77 68 65 72 65 20 4e 20 69 73 20 74 68 65   (where N is the
16430 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
16440 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  ).**           r
16450 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
16460 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
16470 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
16480 20 20 20 72 65 71 75 65 73 74 65 64 20 62 79 20     requested by 
16490 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63 69  the format speci
164a0 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61  fication..*/.cha
164b0 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
164c0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
164d0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
164e0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
164f0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
16500 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
16510 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
16520 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
16530 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
16540 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
16550 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
16560 74 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 32  tem {H17300} <S2
16570 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0000>.**.** The 
16580 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65  SQLite core  use
16590 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
165a0 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
165b0 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
165c0 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
165d0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
165e0 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
165f0 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
16600 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
16610 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
16620 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
16630 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
16640 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
16650 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
16660 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
16670 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
16680 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
16690 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
166a0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
166b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
166c0 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
166d0 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
166e0 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
166f0 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
16700 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
16710 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
16720 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
16730 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
16740 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
16750 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
16760 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
16770 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
16780 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
16790 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
167a0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
167b0 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
167c0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
167d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
167e0 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69  .** Calling sqli
167f0 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
16800 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
16810 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
16820 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
16830 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
16840 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
16850 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
16860 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
16870 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 54  ht be reused.  T
16880 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
16890 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
168a0 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
168b0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
168c0 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
168d0 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
168e0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
168f0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
16900 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
16910 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
16920 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
16930 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
16940 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
16950 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
16960 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
16970 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
16980 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
16990 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
169a0 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
169b0 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
169c0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
169d0 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
169e0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
169f0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
16a00 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
16a10 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
16a20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
16a30 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
16a40 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
16a50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
16a60 6f 72 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  or sqlite3_free(
16a70 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
16a80 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
16a90 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
16aa0 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
16ab0 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
16ac0 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61  location to be a
16ad0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c  t least N bytes,
16ae0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
16af0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
16b00 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  ter.  The memory
16b10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
16b20 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65  e resized is the
16b30 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
16b40 74 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 72  ter.  If the fir
16b50 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
16b60 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16b70 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
16b80 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
16b90 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
16ba0 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
16bb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
16bc0 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
16bd0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
16be0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
16bf0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49  _realloc()..** I
16c00 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
16c10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
16c20 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
16c30 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
16c40 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
16c50 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
16c60 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
16c70 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
16c80 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
16c90 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
16ca0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
16cb0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73  _realloc()..** s
16cc0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16cd0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
16ce0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
16cf0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
16d00 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
16d10 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
16d20 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
16d30 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
16d40 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73  able..** If M is
16d50 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
16d60 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
16d70 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
16d80 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
16d90 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
16da0 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
16db0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
16dc0 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
16dd0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
16de0 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74  _realloc() and t
16df0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
16e00 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
16e10 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   If sqlite3_real
16e20 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
16e30 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
16e40 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
16e50 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
16e60 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20  *.** The memory 
16e70 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
16e80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  te3_malloc() and
16e90 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
16ea0 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
16eb0 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
16ec0 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
16ed0 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a  undary. {END}.**
16ee0 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
16ef0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
16f00 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  f the memory all
16f10 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
16f20 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61  m uses.** the ma
16f30 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
16f40 29 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f  ) and free() pro
16f50 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61  vided by the sta
16f60 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
16f70 0a 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f 77  .** {H17382} How
16f80 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
16f90 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
16fa0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d   the.** SQLITE_M
16fb0 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e  EMORY_SIZE=<i>NN
16fc0 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 65  N</i> C preproce
16fd0 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 72  ssor macro (wher
16fe0 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20  e <i>NNN</i>.** 
16ff0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c 20  is an integer), 
17000 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61  then SQLite crea
17010 74 65 20 61 20 73 74 61 74 69 63 20 61 72 72 61  te a static arra
17020 79 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a  y of at least.**
17030 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65   <i>NNN</i> byte
17040 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73  s in size and us
17050 65 73 20 74 68 61 74 20 61 72 72 61 79 20 66 6f  es that array fo
17060 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
17070 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  amic.** memory a
17080 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
17090 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e   {END}  Addition
170a0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
170b0 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d  tor options.** m
170c0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
170d0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
170e0 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
170f0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
17100 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
17110 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
17120 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
17130 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
17140 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
17150 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
17160 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
17170 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
17180 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
17190 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
171a0 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
171b0 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
171c0 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
171d0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
171e0 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
171f0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e  d..**.** The Win
17200 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
17210 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a  e layer calls.**
17220 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
17230 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
17240 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
17250 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
17260 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
17270 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
17280 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
17290 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
172a0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
172b0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
172c0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
172d0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
172e0 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
172f0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61  ocation errors a
17300 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
17310 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70  .** they are rep
17320 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
17330 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
17340 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
17350 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
17360 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
17370 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
17380 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 33  S:.**.** {H17303
17390 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
173a0 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72  malloc(N)] inter
173b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
173c0 68 65 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  her a pointer to
173d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20  .**           a 
173e0 6e 65 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75  newly checked-ou
173f0 74 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65  t block of at le
17400 61 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 6d  ast N bytes of m
17410 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
17420 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74     that is 8-byt
17430 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 69 74  e aligned, or it
17440 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
17450 20 69 74 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a   it is unable.**
17460 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 66 75             to fu
17470 6c 66 69 6c 6c 20 74 68 65 20 72 65 71 75 65 73  lfill the reques
17480 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 34  t..**.** {H17304
17490 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
174a0 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72  malloc(N)] inter
174b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 4e  face returns a N
174c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a  ULL pointer if.*
174d0 2a 20 20 20 20 20 20 20 20 20 20 20 4e 20 69 73  *           N is
174e0 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
174f0 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  ual to zero..**.
17500 2a 2a 20 7b 48 31 37 33 30 35 7d 20 20 54 68 65  ** {H17305}  The
17510 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50   [sqlite3_free(P
17520 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 6c  )] interface rel
17530 65 61 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 65  eases memory pre
17540 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20  viously.**      
17550 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 66 72       returned fr
17560 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
17570 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
17580 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  3_realloc()],.**
17590 20 20 20 20 20 20 20 20 20 20 20 6d 61 6b 69 6e             makin
175a0 67 20 69 74 20 61 76 61 69 6c 61 62 6c 65 20 66  g it available f
175b0 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  or reuse..**.** 
175c0 7b 48 31 37 33 30 36 7d 20 20 41 20 63 61 6c 6c  {H17306}  A call
175d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
175e0 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 61  e(NULL)] is a ha
175f0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
17600 0a 2a 2a 20 7b 48 31 37 33 31 30 7d 20 20 41 20  .** {H17310}  A 
17610 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
17620 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69  _realloc(0,N)] i
17630 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
17640 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  a call.**       
17650 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f      to [sqlite3_
17660 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a  malloc(N)]..**.*
17670 2a 20 7b 48 31 37 33 31 32 7d 20 20 41 20 63 61  * {H17312}  A ca
17680 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
17690 65 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20  ealloc(P,0)] is 
176a0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20  equivalent to a 
176b0 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  call.**         
176c0 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72    to [sqlite3_fr
176d0 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ee(P)]..**.** {H
176e0 31 37 33 31 35 7d 20 20 54 68 65 20 53 51 4c 69  17315}  The SQLi
176f0 74 65 20 63 6f 72 65 20 75 73 65 73 20 5b 73 71  te core uses [sq
17700 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
17710 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
17720 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  c()],.**        
17730 20 20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f     and [sqlite3_
17740 66 72 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20  free()] for all 
17750 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c  of its memory al
17760 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  location and.** 
17770 20 20 20 20 20 20 20 20 20 20 64 65 61 6c 6c 6f            deallo
17780 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
17790 0a 2a 2a 20 7b 48 31 37 33 31 38 7d 20 20 54 68  .** {H17318}  Th
177a0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  e [sqlite3_reall
177b0 6f 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61  oc(P,N)] interfa
177c0 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
177d0 72 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20  r a pointer.**  
177e0 20 20 20 20 20 20 20 20 20 74 6f 20 61 20 62 6c           to a bl
177f0 6f 63 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f  ock of checked-o
17800 75 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20  ut memory of at 
17810 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
17820 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20   size.**        
17830 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74     that is 8-byt
17840 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20  e aligned, or a 
17850 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
17860 0a 2a 2a 20 7b 48 31 37 33 32 31 7d 20 20 57 68  .** {H17321}  Wh
17870 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
17880 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
17890 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
178a0 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a  nter, it first.*
178b0 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 70 69  *           copi
178c0 65 73 20 74 68 65 20 66 69 72 73 74 20 4b 20 62  es the first K b
178d0 79 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20  ytes of content 
178e0 66 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 20  from P into the 
178f0 6e 65 77 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  newly.**        
17900 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 6c 6f     allocated blo
17910 63 6b 2c 20 77 68 65 72 65 20 4b 20 69 73 20 74  ck, where K is t
17920 68 65 20 6c 65 73 73 65 72 20 6f 66 20 4e 20 61  he lesser of N a
17930 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  nd the size of.*
17940 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20  *           the 
17950 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
17960 7b 48 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b  {H17322}  When [
17970 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17980 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20  P,N)] returns a 
17990 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
179a0 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20  , it first.**   
179b0 20 20 20 20 20 20 20 20 72 65 6c 65 61 73 65 73          releases
179c0 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a   the buffer P..*
179d0 2a 0a 2a 2a 20 7b 48 31 37 33 32 33 7d 20 20 57  *.** {H17323}  W
179e0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  hen [sqlite3_rea
179f0 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72  lloc(P,N)] retur
17a00 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66  ns NULL, the buf
17a10 66 65 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20  fer P is.**     
17a20 20 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69        not modifi
17a30 65 64 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a  ed or released..
17a40 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
17a50 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 30  S:.**.** {A17350
17a60 7d 20 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  }  The pointer a
17a70 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
17a80 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
17a90 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
17aa0 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
17ab0 20 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72    must be either
17ac0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
17ad0 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
17ae0 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
17af0 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61            invoca
17b00 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
17b10 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
17b20 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17b30 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 20  ] that have.**  
17b40 20 20 20 20 20 20 20 20 20 6e 6f 74 20 79 65 74           not yet
17b50 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
17b60 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 31 7d 20 20  **.** {A17351}  
17b70 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
17b80 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
17b90 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
17ba0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  of.**           
17bb0 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
17bc0 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
17bd0 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
17be0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ng.**           
17bf0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
17c00 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
17c10 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
17c20 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
17c30 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
17c40 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
17c50 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
17c60 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
17c70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17c80 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
17c90 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
17ca0 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31   {H17370} <S3021
17cb0 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0>.**.** SQLite 
17cc0 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
17cd0 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
17ce0 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
17cf0 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
17d00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
17d10 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
17d20 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
17d30 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17d40 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
17d50 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
17d60 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
17d70 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
17d80 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  em..**.** INVARI
17d90 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  ANTS:.**.** {H17
17da0 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  371} The [sqlite
17db0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
17dc0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
17dd0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
17de0 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ytes.**         
17df0 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
17e00 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
17e10 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
17e20 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a  ot freed)..**.**
17e30 20 7b 48 31 37 33 37 33 7d 20 54 68 65 20 5b 73   {H17373} The [s
17e40 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
17e50 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
17e60 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
17e70 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20  aximum.**       
17e80 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c     value of [sql
17e90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
17ea0 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
17eb0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
17ec0 20 20 20 20 20 20 20 20 20 20 77 61 73 20 6c 61            was la
17ed0 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  st reset..**.** 
17ee0 7b 48 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c  {H17374} The val
17ef0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
17f00 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
17f10 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20  used()] and.**  
17f20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
17f30 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
17f40 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
17f50 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20   overhead.**    
17f60 20 20 20 20 20 20 61 64 64 65 64 20 62 79 20 53        added by S
17f70 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
17f80 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
17f90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17fa0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ],.**          b
17fb0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
17fc0 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
17fd0 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
17fe0 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20  em library.**   
17ff0 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20         routines 
18000 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
18010 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
18020 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 35 7d  ..**.** {H17375}
18030 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68   The memory high
18040 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
18050 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
18060 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
18070 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
18080 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
18090 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
180a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
180b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
180c0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
180d0 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
180e0 65 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65  e.  The value re
180f0 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  turned.**       
18100 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d     by [sqlite3_m
18110 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
18120 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
18130 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20  water mark.**   
18140 20 20 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20         prior to 
18150 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
18160 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
18170 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
18180 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
18190 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
181a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
181b0 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
181c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
181d0 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
181e0 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 48  ber Generator {H
181f0 31 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a  17390} <S20000>.
18200 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e  **.** SQLite con
18210 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61  tains a high-qua
18220 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64  lity pseudo-rand
18230 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61  om number genera
18240 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20  tor (PRNG) used 
18250 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e  to.** select ran
18260 64 6f 6d 20 52 4f 57 49 44 73 20 77 68 65 6e 20  dom ROWIDs when 
18270 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
18280 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
18290 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
182a0 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
182b0 65 73 74 20 70 6f 73 73 69 62 6c 65 20 52 4f 57  est possible ROW
182c0 49 44 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  ID.  The PRNG is
182d0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
182e0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
182f0 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
18300 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
18310 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
18320 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
18330 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
18340 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
18350 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
18360 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
18370 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20   A call to this 
18380 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
18390 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
183a0 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
183b0 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69   P..**.** The fi
183c0 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
183d0 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
183e0 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
183f0 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
18400 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
18410 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
18420 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
18430 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
18440 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
18450 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
18460 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
18470 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
18480 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75  * On all subsequ
18490 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
184a0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
184b0 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
184c0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
184d0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
184e0 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
184f0 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
18500 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
18510 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
18520 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  NTS:.**.** {H173
18530 39 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  92} The [sqlite3
18540 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29  _randomness(N,P)
18550 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74  ] interface writ
18560 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a  es N bytes of.**
18570 20 20 20 20 20 20 20 20 20 20 68 69 67 68 2d 71            high-q
18580 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
18590 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
185a0 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20  ffer P..*/.void 
185b0 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
185c0 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
185d0 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
185e0 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
185f0 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
18600 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35 30  Callbacks {H1250
18610 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S70100>.**.*
18620 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
18630 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f  egisters a autho
18640 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
18650 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
18660 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
18670 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
18680 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
18690 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
186a0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
186b0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
186c0 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
186d0 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
186e0 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
186f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
18700 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
18710 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18720 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
18730 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
18740 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
18750 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
18760 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
18770 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
18780 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
18790 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
187a0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
187b0 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
187c0 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
187d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
187e0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
187f0 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
18800 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
18810 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75  allowed.  The au
18820 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18830 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
18840 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
18850 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
18860 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
18870 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
18880 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
18890 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
188a0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
188b0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
188c0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
188d0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
188e0 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
188f0 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
18900 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
18910 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
18920 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75  rror.  If the au
18930 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18940 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
18950 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
18960 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
18970 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
18980 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
18990 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
189a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
189b0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
189c0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
189d0 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
189e0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
189f0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
18a00 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
18a10 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
18a20 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
18a30 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
18a40 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
18a50 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
18a60 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c  k.  When the cal
18a70 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
18a80 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
18a90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
18aa0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
18ab0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
18ac0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
18ad0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
18ae0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
18af0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
18b00 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
18b10 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
18b20 65 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 68  ed.  If the auth
18b30 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b  orizer code is [
18b40 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
18b50 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
18b60 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
18b70 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
18b80 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
18b90 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
18ba0 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
18bb0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
18bc0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
18bd0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
18be0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
18bf0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
18c00 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
18c10 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
18c20 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
18c30 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
18c40 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
18c50 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
18c60 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
18c70 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
18c80 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
18c90 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
18ca0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
18cb0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
18cc0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18cd0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
18ce0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
18cf0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
18d00 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18d10 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
18d20 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
18d30 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
18d40 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
18d50 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
18d60 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
18d70 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
18d80 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
18d90 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
18da0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68  e authorized. Th
18db0 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
18dc0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
18dd0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
18de0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
18df0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
18e00 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
18e10 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
18e20 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
18e30 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
18e40 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ized..**.** An a
18e50 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
18e60 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
18e70 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
18e80 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
18e90 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
18ea0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
18eb0 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
18ec0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
18ed0 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
18ee0 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
18ef0 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
18f00 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
18f10 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
18f20 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
18f30 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
18f40 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
18f50 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
18f60 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
18f70 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
18f80 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
18f90 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
18fa0 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
18fb0 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
18fc0 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
18fd0 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
18fe0 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
18ff0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
19000 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
19010 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
19020 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
19030 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
19040 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
19050 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
19060 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
19070 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
19080 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
19090 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
190a0 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
190b0 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
190c0 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
190d0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
190e0 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
190f0 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
19100 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
19110 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
19120 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
19130 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
19140 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
19150 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
19160 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
19170 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
19180 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
19190 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
191a0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
191b0 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
191c0 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
191d0 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79  izer..**.** Only
191e0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
191f0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
19200 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
19210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
19220 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
19230 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
19240 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
19250 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
19260 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
19270 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75    Disable the au
19280 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
19290 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
192a0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
192b0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
192c0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
192d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
192e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
192f0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
19300 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
19310 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
19320 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19330 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
19340 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
19350 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
19360 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
19370 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
19380 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
19390 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
193a0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
193b0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
193c0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
193d0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
193e0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57  ragraph..**.** W
193f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
19400 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
19410 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
19420 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
19430 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
19440 74 20 62 65 20 72 65 70 72 65 70 61 72 65 64 20  t be reprepared 
19450 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
19460 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
19470 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
19480 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
19490 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
194a0 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
194b0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
194c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
194d0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
194e0 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
194f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
19500 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
19510 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
19520 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
19530 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a  ed only during.*
19540 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
19550 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
19560 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a  iants.  Authoriz
19570 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20  ation is not.** 
19580 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67  performed during
19590 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75   statement evalu
195a0 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65  ation in [sqlite
195b0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
195c0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
195d0 2a 2a 20 7b 48 31 32 35 30 31 7d 20 54 68 65 20  ** {H12501} The 
195e0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
195f0 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20  horizer(D,...)] 
19600 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
19610 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  ers a.**        
19620 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c    authorizer cal
19630 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74 61 62  lback with datab
19640 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
19650 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 32 7d  ..**.** {H12502}
19660 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
19670 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
19680 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
19690 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 20  ments are.**    
196a0 20 20 20 20 20 20 62 65 69 6e 67 20 70 61 72 73        being pars
196b0 65 65 64 20 61 6e 64 20 63 6f 6d 70 69 6c 65 64  eed and compiled
196c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 33 7d  ..**.** {H12503}
196d0 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
196e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
196f0 72 6e 73 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  rns any value ot
19700 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  her than.**     
19710 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e       [SQLITE_IGN
19720 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
19730 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
19740 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  NY], then.**    
19750 20 20 20 20 20 20 74 68 65 20 61 70 70 6c 69 63        the applic
19760 61 74 69 6f 6e 20 69 6e 74 65 72 66 61 63 65 20  ation interface 
19770 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64  call that caused
19780 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
19790 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
197a0 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c  back to run shal
197b0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 0a 2a  l fail with an.*
197c0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
197d0 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20  TE_ERROR] error 
197e0 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 70 72  code and an appr
197f0 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65  opriate error me
19800 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ssage..**.** {H1
19810 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65 20 61  2504} When the a
19820 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19830 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
19840 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65 72  TE_OK], the oper
19850 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ation.**        
19860 20 20 64 65 73 63 72 69 62 65 64 20 69 73 20 70    described is p
19870 72 6f 63 65 73 73 65 64 20 6e 6f 72 6d 61 6c 6c  rocessed normall
19880 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 35  y..**.** {H12505
19890 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f  } When the autho
198a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
198b0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
198c0 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 20  ENY], the.**    
198d0 20 20 20 20 20 20 61 70 70 6c 69 63 61 74 69 6f        applicatio
198e0 6e 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  n interface call
198f0 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
19900 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74  .**          aut
19910 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19920 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61   to run shall fa
19930 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  il.**          w
19940 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45  ith an [SQLITE_E
19950 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65  RROR] error code
19960 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
19970 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  ssage.**        
19980 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61    explaining tha
19990 74 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  t access is deni
199a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30  ed..**.** {H1250
199b0 36 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  6} If the author
199c0 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32  izer code (the 2
199d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
199e0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a  the authorizer.*
199f0 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
19a00 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45 5f  ack) is [SQLITE_
19a10 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61 75  READ] and the au
19a20 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
19a30 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  k returns.**    
19a40 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47        [SQLITE_IG
19a50 4e 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68 65 20  NORE], then the 
19a60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
19a70 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
19a80 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
19a90 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76   insert a NULL v
19aa0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
19ab0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
19ac0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
19ad0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  e.**          be
19ae0 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
19af0 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
19b00 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
19b10 7b 48 31 32 35 30 37 7d 20 49 66 20 74 68 65 20  {H12507} If the 
19b20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
19b30 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74  (the 2nd paramet
19b40 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
19b50 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  izer.**         
19b60 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e   callback) is an
19b70 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ything other tha
19b80 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c  n [SQLITE_READ],
19b90 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
19ba0 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b 53    a return of [S
19bb0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61  QLITE_IGNORE] ha
19bc0 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63  s the same effec
19bd0 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  t as [SQLITE_DEN
19be0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31  Y]..**.** {H1251
19bf0 30 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72  0} The first par
19c00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
19c10 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
19c20 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  k is a copy of.*
19c30 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74  *          the t
19c40 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
19c50 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
19c60 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
19c70 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
19c80 2a 20 7b 48 31 32 35 31 31 7d 20 54 68 65 20 73  * {H12511} The s
19c90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19ca0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
19cb0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
19cc0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
19cd0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
19ce0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
19cf0 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75  fies the particu
19d00 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20  lar action.**   
19d10 20 20 20 20 20 20 20 74 6f 20 62 65 20 61 75 74         to be aut
19d20 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  horized..**.** {
19d30 48 31 32 35 31 32 7d 20 54 68 65 20 74 68 69 72  H12512} The thir
19d40 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
19d50 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
19d60 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a  e callback are.*
19d70 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
19d80 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
19d90 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 0a  gs that contain.
19da0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 69  **          addi
19db0 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61  tional details a
19dc0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
19dd0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
19de0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 30 7d  ..**.** {H12520}
19df0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73   Each call to [s
19e00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
19e10 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69 64  rizer()] overrid
19e20 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  es.**          a
19e30 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69 6e  ny previously in
19e40 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a  stalled authoriz
19e50 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32  er..**.** {H1252
19e60 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72  1} A NULL author
19e70 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20  izer means that 
19e80 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  no authorization
19e90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
19ea0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
19eb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 32 7d  ..**.** {H12522}
19ec0 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74   The default aut
19ed0 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e  horizer is NULL.
19ee0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
19ef0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
19f00 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
19f10 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
19f20 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
19f30 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
19f40 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
19f50 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
19f60 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
19f70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
19f80 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
19f90 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20 3c 48  odes {H12590} <H
19fa0 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  12500>.**.** The
19fb0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
19fc0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
19fd0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
19fe0 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
19ff0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1a000 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1a010 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1a020 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1a030 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1a040 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1a050 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1a060 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1a070 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1a080 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1a090 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1a0a0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1a0b0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1a0c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
1a0d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1a0e0 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
1a0f0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
1a100 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
1a110 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
1a120 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
1a130 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
1a140 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
1a150 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
1a160 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
1a170 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1a180 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b  r Action Codes {
1a190 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30 30 3e  H12550} <H12500>
1a1a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1a1b0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1a1c0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
1a1d0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
1a1e0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
1a1f0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
1a200 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
1a210 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
1a220 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
1a230 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1a240 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
1a250 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1a260 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
1a270 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
1a280 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
1a290 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1a2a0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
1a2b0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
1a2c0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
1a2d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1a2e0 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
1a2f0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
1a300 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
1a310 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
1a320 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
1a330 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
1a340 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
1a350 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
1a360 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1a370 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
1a380 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
1a390 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
1a3a0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
1a3b0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
1a3c0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
1a3d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1a3e0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
1a3f0 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
1a400 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
1a410 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1a420 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1a430 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
1a440 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
1a450 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
1a460 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d  .  The 6th param
1a470 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1a480 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
1a490 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
1a4a0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
1a4b0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
1a4c0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
1a4d0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
1a4e0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
1a4f0 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
1a500 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
1a510 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
1a520 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
1a530 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  code..**.** INVA
1a540 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
1a550 31 32 35 35 31 7d 20 54 68 65 20 73 65 63 6f 6e  12551} The secon
1a560 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 61  d parameter to a
1a570 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  n.**          [s
1a580 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1a590 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1a5a0 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61  er callback] sha
1a5b0 6c 6c 20 62 65 20 61 6e 20 69 6e 74 65 67 65 72  ll be an integer
1a5c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
1a5d0 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68  LITE_COPY | auth
1a5e0 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 74 68 61  orizer code] tha
1a5f0 74 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  t specifies what
1a600 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20   action.**      
1a610 20 20 20 20 69 73 20 62 65 69 6e 67 20 61 75 74      is being aut
1a620 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  horized..**.** {
1a630 48 31 32 35 35 32 7d 20 54 68 65 20 33 72 64 20  H12552} The 3rd 
1a640 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1a650 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  rs to the.**    
1a660 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
1a670 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1a680 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61  authorization ca
1a690 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20 20 20 20  llback].**      
1a6a0 20 20 20 20 73 68 61 6c 6c 20 62 65 20 70 61 72      shall be par
1a6b0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
1a6c0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
1a6d0 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ch.**          [
1a6e0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75  SQLITE_COPY | au
1a6f0 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 69  thorizer code] i
1a700 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1a710 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  cond parameter..
1a720 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 33 7d 20 54  **.** {H12553} T
1a730 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1a740 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
1a750 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
1a760 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1a770 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1a780 6b 5d 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20  k] shall be the 
1a790 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  name.**         
1a7a0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1a7b0 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e   (example: "main
1a7c0 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 2e 29  ", "temp", etc.)
1a7d0 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a   if applicable..
1a7e0 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 34 7d 20 54  **.** {H12554} T
1a7f0 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
1a800 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
1a810 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
1a820 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1a830 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1a840 6b 5d 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20  k] shall be the 
1a850 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  name.**         
1a860 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1a870 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1a880 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1a890 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20  nsible for.**   
1a8a0 20 20 20 20 20 20 20 74 68 65 20 61 63 63 65 73         the acces
1a8b0 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
1a8c0 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
1a8d0 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
1a8e0 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 20 20 20  ctly from.**    
1a8f0 20 20 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20        top-level 
1a900 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
1a910 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a920 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a930 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
1a940 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
1a950 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
1a960 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1a970 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
1a980 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
1a990 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1a9a0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1a9b0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1a9c0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1a9d0 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
1a9e0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1a9f0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1aa00 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1aa10 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
1aa20 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1aa30 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1aa40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1aa50 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1aa60 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
1aa70 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1aa80 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1aa90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1aaa0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1aab0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
1aac0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1aad0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1aae0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1aaf0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1ab00 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
1ab10 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1ab20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ab30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ab40 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
1ab50 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
1ab60 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1ab70 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1ab80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ab90 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
1aba0 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
1abb0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1abc0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1abd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1abe0 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
1abf0 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
1ac00 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ac10 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ac20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ac30 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
1ac40 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
1ac50 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1ac60 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1ac70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ac80 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
1ac90 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
1aca0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1acb0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1acc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1acd0 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
1ace0 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
1acf0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1ad00 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ad10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ad20 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
1ad30 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
1ad40 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1ad50 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1ad60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1ad70 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
1ad80 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
1ad90 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1ada0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1adb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1adc0 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
1add0 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
1ade0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1adf0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ae00 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1ae10 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1ae20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
1ae30 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1ae40 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ae50 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1ae60 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
1ae70 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
1ae80 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1ae90 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1aea0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
1aeb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1aec0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1aed0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1aee0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1aef0 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
1af00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
1af10 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
1af20 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
1af30 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
1af40 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
1af50 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
1af60 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1af70 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1af80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1af90 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
1afa0 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
1afb0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1afc0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1afd0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1afe0 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
1aff0 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
1b000 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1b010 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b020 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b030 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
1b040 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
1b050 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1b060 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1b070 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b080 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
1b090 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
1b0a0 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
1b0b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b0c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b0d0 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
1b0e0 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
1b0f0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1b100 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b110 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b120 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
1b130 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
1b140 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
1b150 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1b160 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b170 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
1b180 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
1b190 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
1b1a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b1b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b1c0 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
1b1d0 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
1b1e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1b1f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b200 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1b210 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
1b220 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
1b230 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1b240 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1b250 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1b260 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
1b270 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
1b280 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1b290 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1b2a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
1b2b0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
1b2c0 20 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 69    31   /* Functi
1b2d0 6f 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  on Name   NULL  
1b2e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b2f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
1b300 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b310 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
1b320 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
1b330 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
1b340 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
1b350 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 32  g Functions {H12
1b360 32 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a  280} <S60400>.**
1b370 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
1b380 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1b390 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
1b3a0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
1b3b0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
1b3c0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
1b3d0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
1b3e0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
1b3f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1b400 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
1b410 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1b420 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1b430 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
1b440 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
1b450 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
1b460 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
1b470 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
1b480 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1b490 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  * The callback r
1b4a0 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72  eturns a UTF-8 r
1b4b0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
1b4c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
1b4d0 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61  xt.** as the sta
1b4e0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
1b4f0 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20  ins executing.  
1b500 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62  Additional callb
1b510 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73  acks occur.** as
1b520 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1b530 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1b540 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1b550 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1b560 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1b570 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1b580 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1b590 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a  s the trigger..*
1b5a0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
1b5b0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1b5c0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1b5d0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
1b5e0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
1b5f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
1b600 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70 72  inishes.  The pr
1b610 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
1b620 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
1b630 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1b640 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
1b650 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
1b660 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
1b670 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
1b680 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
1b690 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  run..**.** INVAR
1b6a0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1b6b0 32 32 38 31 7d 20 54 68 65 20 63 61 6c 6c 62 61  2281} The callba
1b6c0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1b6d0 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74  stered by [sqlit
1b6e0 65 33 5f 74 72 61 63 65 28 29 5d 20 0a 2a 2a 20  e3_trace()] .** 
1b6f0 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 62           shall b
1b700 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20  e invoked.**    
1b710 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61        whenever a
1b720 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1b730 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20  first begins to 
1b740 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20  execute and.**  
1b750 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72          whenever
1b760 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72   a trigger subpr
1b770 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65 67 69  ogram first begi
1b780 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  ns to run..**.**
1b790 20 7b 48 31 32 32 38 32 7d 20 45 61 63 68 20 63   {H12282} Each c
1b7a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1b7b0 74 72 61 63 65 28 29 5d 20 73 68 61 6c 6c 20 6f  trace()] shall o
1b7c0 76 65 72 72 69 64 65 20 74 68 65 20 70 72 65 76  verride the prev
1b7d0 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20  iously.**       
1b7e0 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 72     registered tr
1b7f0 61 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ace callback..**
1b800 0a 2a 2a 20 7b 48 31 32 32 38 33 7d 20 41 20 4e  .** {H12283} A N
1b810 55 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c 62 61  ULL trace callba
1b820 63 6b 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65  ck shall disable
1b830 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   tracing..**.** 
1b840 7b 48 31 32 32 38 34 7d 20 54 68 65 20 66 69 72  {H12284} The fir
1b850 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1b860 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  he trace callbac
1b870 6b 20 73 68 61 6c 6c 20 62 65 20 61 20 63 6f 70  k shall be a cop
1b880 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  y of.**         
1b890 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68 69   the pointer whi
1b8a0 63 68 20 77 61 73 20 74 68 65 20 33 72 64 20 61  ch was the 3rd a
1b8b0 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
1b8c0 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a  te3_trace()]..**
1b8d0 0a 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54 68 65  .** {H12285} The
1b8e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1b8f0 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
1b900 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20  llback is a.**  
1b910 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
1b920 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1b930 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
1b940 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 78  the original tex
1b950 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  t.**          of
1b960 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1b970 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 61 73  nt as it was pas
1b980 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65  sed into [sqlite
1b990 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a  3_prepare_v2()].
1b9a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
1b9b0 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f  he equivalent, o
1b9c0 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  r an SQL comment
1b9d0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
1b9e0 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20  beginning.**    
1b9f0 20 20 20 20 20 20 6f 66 20 61 20 74 72 69 67 67        of a trigg
1ba00 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a  er subprogram..*
1ba10 2a 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20 54 68  *.** {H12287} Th
1ba20 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1ba30 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1ba40 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  y [sqlite3_profi
1ba50 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  le()] is invoked
1ba60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20  .**          as 
1ba70 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
1ba80 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a  nt finishes..**.
1ba90 2a 2a 20 7b 48 31 32 32 38 38 7d 20 54 68 65 20  ** {H12288} The 
1baa0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1bab0 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63  to the profile c
1bac0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
1bad0 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  y of.**         
1bae0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
1baf0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  er to [sqlite3_p
1bb00 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rofile()]..**.**
1bb10 20 7b 48 31 32 32 38 39 7d 20 54 68 65 20 73 65   {H12289} The se
1bb20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1bb30 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
1bb40 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20  llback is a.**  
1bb50 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72          zero-ter
1bb60 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1bb70 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69  ring that contai
1bb80 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20  ns the complete 
1bb90 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20  text of.**      
1bba0 20 20 20 20 74 68 65 20 53 51 4c 20 73 74 61 74      the SQL stat
1bbb0 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20  ement as it was 
1bbc0 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73 71  processed by [sq
1bbd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1bbe0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
1bbf0 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
1bc00 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39 30  t..**.** {H12290
1bc10 7d 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61  } The third para
1bc20 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f  meter to the pro
1bc30 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  file callback is
1bc40 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20   an estimate.** 
1bc50 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
1bc60 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65  number of nanose
1bc70 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c  conds of wall-cl
1bc80 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72 65  ock time require
1bc90 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
1bca0 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74 61   run the SQL sta
1bcb0 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 72  tement from star
1bcc0 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a  t to finish..*/.
1bcd0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
1bce0 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
1bcf0 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
1bd00 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28  , void(*xTrace)(
1bd10 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
1bd20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49  *), void*);.SQLI
1bd30 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
1bd40 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
1bd50 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
1bd60 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
1bd70 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1bd80 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
1bd90 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
1bda0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
1bdb0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
1bdc0 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30 7d  llbacks {H12910}
1bdd0 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60400>.**.** 
1bde0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e  This routine con
1bdf0 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61  figures a callba
1be00 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68  ck function - th
1be10 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61  e.** progress ca
1be20 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73  llback - that is
1be30 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
1be40 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
1be50 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c  g.** running cal
1be60 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1be70 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
1be80 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20  _step()] and.** 
1be90 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1bea0 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70  le()].  An examp
1beb0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
1bec0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
1bed0 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
1bee0 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
1bef0 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
1bf00 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  * If the progres
1bf10 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
1bf20 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
1bf30 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a   operation is.**
1bf40 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54   interrupted.  T
1bf50 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20  his feature can 
1bf60 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  be used to imple
1bf70 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65  ment a.** "Cance
1bf80 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47  l" button on a G
1bf90 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c  UI progress dial
1bfa0 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68  og box..**.** Th
1bfb0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1bfc0 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  er must not do a
1bfd0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1bfe0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1bff0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c000 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1c010 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1c020 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
1c030 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1c040 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1c050 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c060 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1c070 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1c080 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1c090 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1c0a0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1c0b0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49  ragraph..**.** I
1c0c0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1c0d0 20 7b 48 31 32 39 31 31 7d 20 54 68 65 20 63 61   {H12911} The ca
1c0e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1c0f0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1c100 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1c110 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20  andler().**     
1c120 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20       is invoked 
1c130 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
1c140 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
1c150 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20   calls to.**    
1c160 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
1c170 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tep()]..**.** {H
1c180 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72  12912} The progr
1c190 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ess callback is 
1c1a0 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72  invoked once for
1c1b0 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c   every N virtual
1c1c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63  .**          mac
1c1d0 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68  hine opcodes, wh
1c1e0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
1c1f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
1c200 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1c210 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73  [sqlite3_progres
1c220 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c  s_handler()] cal
1c230 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72 65  l that registere
1c240 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  d.**          th
1c250 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20  e callback.  If 
1c260 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31  N is less than 1
1c270 2c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  , sqlite3_progre
1c280 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20  ss_handler().** 
1c290 20 20 20 20 20 20 20 20 20 61 63 74 73 20 61 73           acts as
1c2a0 20 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67 72   if a NULL progr
1c2b0 65 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64 20  ess handler had 
1c2c0 62 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e 0a  been specified..
1c2d0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20 54  **.** {H12913} T
1c2e0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1c2f0 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69  back itself is i
1c300 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
1c310 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20   third.**       
1c320 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73     argument to s
1c330 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1c340 68 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a  handler()..**.**
1c350 20 7b 48 31 32 39 31 34 7d 20 54 68 65 20 66 6f   {H12914} The fo
1c360 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
1c370 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1c380 73 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20 61  s_handler() is a
1c390 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f 69  .**          voi
1c3a0 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  d pointer passed
1c3b0 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73   to the progress
1c3c0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
1c3d0 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65        function e
1c3e0 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69  ach time it is i
1c3f0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nvoked..**.** {H
1c400 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c  12915} If a call
1c410 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
1c420 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20  p()] results in 
1c430 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63  fewer than N opc
1c440 6f 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  odes.**         
1c450 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c   being executed,
1c460 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
1c470 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ss callback is n
1c480 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  ever invoked..**
1c490 0a 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45 76 65  .** {H12916} Eve
1c4a0 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ry call to [sqli
1c4b0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1c4c0 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20  dler()].**      
1c4d0 20 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 61      overwrites a
1c4e0 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ny previously re
1c4f0 67 69 73 74 65 72 65 64 20 70 72 6f 67 72 65 73  gistered progres
1c500 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  s handler..**.**
1c510 20 7b 48 31 32 39 31 37 7d 20 49 66 20 74 68 65   {H12917} If the
1c520 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1c530 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  r callback is NU
1c540 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72  LL then no progr
1c550 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ess.**          
1c560 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b  handler is invok
1c570 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  ed..**.** {H1291
1c580 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  8} If the progre
1c590 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
1c5a0 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68  rns a result oth
1c5b0 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a  er than 0, then.
1c5c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1c5d0 62 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66  behavior is a if
1c5e0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
1c5f0 75 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20  upt()] had been 
1c600 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20 20  called..**      
1c610 20 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f 0a      <S30500>.*/.
1c620 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
1c630 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
1c640 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
1c650 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
1c660 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1c670 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
1c680 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
1c690 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20  ection {H12700} 
1c6a0 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S40200>.**.** T
1c6b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
1c6c0 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
1c6d0 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65  abase file whose
1c6e0 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62   name is given b
1c6f0 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  y the.** filenam
1c700 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20  e argument. The 
1c710 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1c720 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
1c730 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
1c740 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1c750 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1c760 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
1c770 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1c780 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
1c790 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
1c7a0 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61 73  16(). A [databas
1c7b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1c7c0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
1c7d0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
1c7e0 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
1c7f0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
1c800 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
1c810 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
1c820 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
1c830 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
1c840 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1c850 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
1c860 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
1c870 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
1c880 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
1c890 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
1c8a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
1c8b0 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65 20   object. If the 
1c8c0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1c8d0 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
1c8e0 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
1c8f0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
1c900 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
1c910 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
1c920 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
1c930 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a   returned.  The.
1c940 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1c950 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
1c960 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
1c970 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
1c980 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
1c990 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
1c9a0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
1c9b0 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  of the error..**
1c9c0 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
1c9d0 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
1c9e0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1c9f0 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
1ca00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1ca10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ca20 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
1ca30 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
1ca40 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1ca50 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
1ca60 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
1ca70 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
1ca80 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
1ca90 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
1caa0 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
1cab0 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
1cac0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
1cad0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1cae0 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
1caf0 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
1cb00 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
1cb10 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
1cb20 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
1cb30 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
1cb40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1cb50 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
1cb60 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
1cb70 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
1cb80 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1cb90 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
1cba0 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
1cbb0 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
1cbc0 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
1cbd0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1cbe0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
1cbf0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
1cc00 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  er can take one 
1cc10 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
1cc20 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
1cc30 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
1cc40 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
1cc50 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1cc60 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c  NOMUTEX] or [SQL
1cc70 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
1cc80 45 58 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a  EX] flags:.**.**
1cc90 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51   <dl>.** <dt>[SQ
1cca0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1ccb0 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
1ccc0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1ccd0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
1cce0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
1ccf0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
1cd00 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
1cd10 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
1cd20 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1cd30 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49  .**.** <dt>[SQLI
1cd40 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1cd50 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1cd60 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1cd70 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1cd80 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
1cd90 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
1cda0 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
1cdb0 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
1cdc0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
1cdd0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1cde0 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
1cdf0 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
1ce00 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
1ce10 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
1ce20 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
1ce30 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  returned.</dd>.*
1ce40 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45  *.** <dt>[SQLITE
1ce50 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1ce60 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
1ce70 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
1ce80 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1ce90 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1cea0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1ceb0 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
1cec0 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64  es it if.** it d
1ced0 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
1cee0 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
1cef0 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
1cf00 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
1cf10 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
1cf20 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1cf30 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
1cf40 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
1cf50 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
1cf60 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1cf70 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
1cf80 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
1cf90 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1cfa0 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f  n above or one o
1cfb0 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f  f the combinatio
1cfc0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63  ns shown above c
1cfd0 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20  ombined.** with 
1cfe0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1cff0 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51  _NOMUTEX] or [SQ
1d000 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1d010 54 45 58 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74  TEX] flags,.** t
1d020 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1d030 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
1d040 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c  *.** If the [SQL
1d050 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1d060 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
1d070 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1d080 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1d090 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
1d0a0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
1d0b0 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
1d0c0 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
1d0d0 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
1d0e0 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
1d0f0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1d100 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
1d110 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
1d120 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
1d130 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
1d140 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1d150 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
1d160 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
1d170 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1d180 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
1d190 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
1d1a0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1d1b0 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
1d1c0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
1d1d0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  time..**.** If t
1d1e0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
1d1f0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
1d200 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1d210 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
1d220 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
1d230 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
1d240 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nnection.  This 
1d250 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1d260 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
1d270 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
1d280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1d290 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
1d2a0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1d2b0 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
1d2c0 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
1d2d0 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
1d2e0 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
1d2f0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
1d300 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
1d310 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
1d320 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
1d330 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
1d340 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
1d350 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
1d360 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
1d370 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
1d380 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
1d390 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
1d3a0 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
1d3b0 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
1d3c0 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  * If the filenam
1d3d0 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
1d3e0 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
1d3f0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
1d400 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
1d410 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
1d420 74 65 64 2e 20 20 54 68 69 73 20 70 72 69 76 61  ted.  This priva
1d430 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  te database will
1d440 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   be.** automatic
1d450 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20  ally deleted as 
1d460 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61  soon as the data
1d470 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1d480 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
1d490 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
1d4a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1d4b0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
1d4c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
1d4d0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1d4e0 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
1d4f0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
1d500 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
1d510 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
1d520 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1d530 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
1d540 2e 20 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  .  If the fourth
1d550 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1d560 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1d570 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
1d580 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1d590 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
1d5a0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
1d5b0 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
1d5c0 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
1d5d0 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
1d5e0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
1d5f0 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
1d600 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1d610 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
1d620 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
1d630 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
1d640 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
1d650 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
1d660 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
1d670 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
1d680 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
1d690 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
1d6a0 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
1d6b0 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
1d6c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1d6d0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1d6e0 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 49  en_v2()..**.** I
1d6f0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1d700 20 7b 48 31 32 37 30 31 7d 20 54 68 65 20 5b 73   {H12701} The [s
1d710 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
1d720 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1d730 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  )], and.**      
1d740 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1d750 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
1d760 65 73 20 63 72 65 61 74 65 20 61 20 6e 65 77 0a  es create a new.
1d770 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
1d780 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d790 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  ] associated wit
1d7a0 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  h.**          th
1d7b0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1d7c0 67 69 76 65 6e 20 69 6e 20 74 68 65 69 72 20 66  given in their f
1d7d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
1d7e0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 32 7d 20 54  **.** {H12702} T
1d7f0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1d800 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
1d810 74 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20  ted as UTF-8.** 
1d820 20 20 20 20 20 20 20 20 20 66 6f 72 20 5b 73 71           for [sq
1d830 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e  lite3_open()] an
1d840 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  d [sqlite3_open_
1d850 76 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46  v2()] and as UTF
1d860 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  -16.**          
1d870 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1d880 74 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71  te order for [sq
1d890 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
1d8a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 33 7d 20  .**.** {H12703} 
1d8b0 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
1d8c0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
1d8d0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1d8e0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
1d8f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1d900 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1d910 28 29 5d 20 77 72 69 74 65 73 20 61 20 70 6f 69  ()] writes a poi
1d920 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a  nter to a new.**
1d930 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
1d940 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1d950 69 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a  into *ppDb..**.*
1d960 2a 20 7b 48 31 32 37 30 34 7d 20 54 68 65 20 5b  * {H12704} The [
1d970 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1d980 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1d990 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ()], and.**     
1d9a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
1d9b0 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
1d9c0 63 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ces return [SQLI
1d9d0 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63  TE_OK] upon succ
1d9e0 65 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ess,.**         
1d9f0 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61   or an appropria
1da00 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
1da10 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  on failure..**.*
1da20 2a 20 7b 48 31 32 37 30 36 7d 20 54 68 65 20 64  * {H12706} The d
1da30 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f  efault text enco
1da40 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64  ding for a new d
1da50 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20  atabase created 
1da60 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
1da70 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28    [sqlite3_open(
1da80 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  )] or [sqlite3_o
1da90 70 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62  pen_v2()] will b
1daa0 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b  e UTF-8..**.** {
1dab0 48 31 32 37 30 37 7d 20 54 68 65 20 64 65 66 61  H12707} The defa
1dac0 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  ult text encodin
1dad0 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61  g for a new data
1dae0 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69  base created usi
1daf0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
1db00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1db10 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36  ] will be UTF-16
1db20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 39 7d  ..**.** {H12709}
1db30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1db40 65 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 61  en(F,D)] interfa
1db50 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  ce is equivalent
1db60 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1db70 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1db80 28 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 65  (F,D,G,0)] where
1db90 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
1dba0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
1dbb0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1dbc0 44 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f  DWRITE]|[SQLITE_
1dbd0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a  OPEN_CREATE]..**
1dbe0 0a 2a 2a 20 7b 48 31 32 37 31 31 7d 20 49 66 20  .** {H12711} If 
1dbf0 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
1dc00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1dc10 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f  _v2(F,D,G,V)] co
1dc20 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20  ntains the.**   
1dc30 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65         bit value
1dc40 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
1dc50 41 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65  ADONLY] then the
1dc60 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1dc70 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
1dc80 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79  for reading only
1dc90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 32 7d  ..**.** {H12712}
1dca0 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
1dcb0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1dcc0 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
1dcd0 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  ] contains the.*
1dce0 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76  *          bit v
1dcf0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  alue [SQLITE_OPE
1dd00 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 74 68 65  N_READWRITE] the
1dd10 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
1dd20 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20  s opened.**     
1dd30 20 20 20 20 20 72 65 61 64 69 6e 67 20 61 6e 64       reading and
1dd40 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
1dd50 69 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 61  ible, or for rea
1dd60 64 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 65  ding only if the
1dd70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
1dd80 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65  e is write prote
1dd90 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72  cted by the oper
1dda0 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a  ating system..**
1ddb0 0a 2a 2a 20 7b 48 31 32 37 31 33 7d 20 49 66 20  .** {H12713} If 
1ddc0 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
1ddd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1dde0 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d  _v2(F,D,G,V)] om
1ddf0 69 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  its the.**      
1de00 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
1de10 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1de20 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  E] and the datab
1de30 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1de40 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75           previou
1de50 73 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  sly exist, an er
1de60 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1de70 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 34 7d 20  .**.** {H12714} 
1de80 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  If the G paramet
1de90 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  er to [sqlite3_o
1dea0 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen_v2(F,D,G,V)]
1deb0 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a   contains the.**
1dec0 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61            bit va
1ded0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  lue [SQLITE_OPEN
1dee0 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65  _CREATE] and the
1def0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1df00 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  ot.**          p
1df10 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c  reviously exist,
1df20 20 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74   then an attempt
1df30 20 69 73 20 6d 61 64 65 20 74 6f 20 63 72 65 61   is made to crea
1df40 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  te and.**       
1df50 20 20 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68     initialize th
1df60 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a  e database..**.*
1df70 2a 20 7b 48 31 32 37 31 37 7d 20 49 66 20 74 68  * {H12717} If th
1df80 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1df90 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
1dfa0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
1dfb0 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20  3_open16()],.** 
1dfc0 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
1dfd0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1dfe0 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1dff0 68 65 6e 20 61 6e 20 70 72 69 76 61 74 65 2c 0a  hen an private,.
1e000 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65  **          ephe
1e010 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79  meral, in-memory
1e020 20 64 61 74 61 62 61 73 65 20 69 73 20 63 72 65   database is cre
1e030 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
1e040 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20  nection..**     
1e050 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51       <todo>Is SQ
1e060 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1e070 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  |SQLITE_OPEN_REA
1e080 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a  DWRITE required.
1e090 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73  **          in s
1e0a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1e0b0 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b  ?</todo>.**.** {
1e0c0 48 31 32 37 31 39 7d 20 49 66 20 74 68 65 20 66  H12719} If the f
1e0d0 69 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20  ilename is NULL 
1e0e0 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  or an empty stri
1e0f0 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
1e100 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  te,.**          
1e110 65 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69 73  ephemeral on-dis
1e120 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
1e130 62 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20  be created..**  
1e140 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73          <todo>Is
1e150 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
1e160 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ATE|SQLITE_OPEN_
1e170 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69 72  READWRITE requir
1e180 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ed.**          i
1e190 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  n sqlite3_open_v
1e1a0 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a  2()?</todo>.**.*
1e1b0 2a 20 7b 48 31 32 37 32 31 7d 20 54 68 65 20 5b  * {H12721} The [
1e1c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e1d0 69 6f 6e 5d 20 63 72 65 61 74 65 64 20 62 79 20  ion] created by 
1e1e0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1e1f0 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20 20  (F,D,G,V)].**   
1e200 20 20 20 20 20 20 20 77 69 6c 6c 20 75 73 65 20         will use 
1e210 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1e220 5d 20 6f 62 6a 65 63 74 20 69 64 65 6e 74 69 66  ] object identif
1e230 69 65 64 20 62 79 20 74 68 65 20 56 20 70 61 72  ied by the V par
1e240 61 6d 65 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20  ameter,.**      
1e250 20 20 20 20 6f 72 20 74 68 65 20 64 65 66 61 75      or the defau
1e260 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
1e270 20 6f 62 6a 65 63 74 20 69 66 20 56 20 69 73 20   object if V is 
1e280 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1e290 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 33 7d 20 54  **.** {H12723} T
1e2a0 77 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  wo [database con
1e2b0 6e 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20 73  nections] will s
1e2c0 68 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61  hare a common ca
1e2d0 63 68 65 20 69 66 20 62 6f 74 68 20 77 65 72 65  che if both were
1e2e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65  .**          ope
1e2f0 6e 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d  ned with the sam
1e300 65 20 56 46 53 20 77 68 69 6c 65 20 5b 73 68 61  e VFS while [sha
1e310 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
1e320 77 61 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 0a  was enabled and.
1e330 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 62  **          if b
1e340 6f 74 68 20 66 69 6c 65 6e 61 6d 65 73 20 63 6f  oth filenames co
1e350 6d 70 61 72 65 20 65 71 75 61 6c 20 75 73 69 6e  mpare equal usin
1e360 67 20 6d 65 6d 63 6d 70 28 29 20 61 66 74 65 72  g memcmp() after
1e370 20 68 61 76 69 6e 67 20 62 65 65 6e 0a 2a 2a 20   having been.** 
1e380 20 20 20 20 20 20 20 20 20 70 72 6f 63 65 73 73           process
1e390 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
1e3a0 65 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c 50 61  e3_vfs | xFullPa
1e3b0 74 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64 20 6f  thname] method o
1e3c0 66 20 74 68 65 20 56 46 53 2e 0a 2a 2f 0a 69 6e  f the VFS..*/.in
1e3d0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
1e3e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
1e3f0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1e400 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1e410 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
1e420 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1e430 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1e440 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1e450 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1e460 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
1e470 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
1e480 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1e490 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
1e4a0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1e4b0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1e4c0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1e4d0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1e4e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
1e4f0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
1e500 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1e510 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1e520 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
1e530 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
1e540 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1e550 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1e560 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
1e570 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
1e580 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
1e590 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
1e5a0 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
1e5b0 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
1e5c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e5d0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
1e5e0 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48 31  And Messages {H1
1e5f0 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a  2800} <S60200>.*
1e600 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1e610 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72  _errcode() inter
1e620 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
1e630 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
1e640 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
1e650 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
1e660 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  de] for the most
1e670 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73   recent failed s
1e680 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
1e690 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  l.** associated 
1e6a0 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
1e6b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66   connection]. If
1e6c0 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c   a prior API cal
1e6d0 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20  l failed.** but 
1e6e0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
1e6f0 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64  API call succeed
1e700 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ed, the return v
1e710 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  alue from.** sql
1e720 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
1e730 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
1e740 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
1e750 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1e760 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1e770 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1e780 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1e790 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1e7a0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1e7b0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1e7c0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1e7d0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** Memory to ho
1e7e0 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
1e7f0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
1e800 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
1e810 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
1e820 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
1e830 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
1e840 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
1e850 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
1e860 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
1e870 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
1e880 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
1e890 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
1e8a0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1e8b0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
1e8c0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
1e8d0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ns..**.** If an 
1e8e0 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
1e8f0 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
1e900 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
1e910 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
1e920 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
1e930 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
1e940 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
1e950 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
1e960 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
1e970 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
1e980 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
1e990 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1e9a0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 31 7d  :.**.** {H12801}
1e9b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   The [sqlite3_er
1e9c0 72 63 6f 64 65 28 44 29 5d 20 69 6e 74 65 72 66  rcode(D)] interf
1e9d0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1e9e0 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20  numeric.**      
1e9f0 20 20 20 20 5b 72 65 73 75 6c 74 20 63 6f 64 65      [result code
1ea00 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72  ] or [extended r
1ea10 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
1ea20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
1ea30 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 61  y.**          fa
1ea40 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63  iled interface c
1ea50 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77  all associated w
1ea60 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
1ea70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
1ea80 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 33 7d 20  .**.** {H12803} 
1ea90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  The [sqlite3_err
1eaa0 6d 73 67 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c  msg(D)] and [sql
1eab0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29  ite3_errmsg16(D)
1eac0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
1ead0 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
1eae0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
1eaf0 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
1eb00 69 62 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ibes.**         
1eb10 20 74 68 65 20 65 72 72 6f 72 20 69 6e 20 74 68   the error in th
1eb20 65 20 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c  e mostly recentl
1eb30 79 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61  y failed interfa
1eb40 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20  ce call,.**     
1eb50 20 20 20 20 20 65 6e 63 6f 64 65 64 20 61 73 20       encoded as 
1eb60 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1eb70 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
1eb80 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38  ely..**.** {H128
1eb90 30 37 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20  07} The strings 
1eba0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1ebb0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61  ite3_errmsg()] a
1ebc0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  nd [sqlite3_errm
1ebd0 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  sg16()].**      
1ebe0 20 20 20 20 61 72 65 20 76 61 6c 69 64 20 75 6e      are valid un
1ebf0 74 69 6c 20 74 68 65 20 6e 65 78 74 20 53 51 4c  til the next SQL
1ec00 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 63 61  ite interface ca
1ec10 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30  ll..**.** {H1280
1ec20 38 7d 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20  8} Calls to API 
1ec30 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f  routines that do
1ec40 20 6e 6f 74 20 72 65 74 75 72 6e 20 61 6e 20 65   not return an e
1ec50 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
1ec60 20 20 20 20 20 20 28 65 78 61 6d 70 6c 65 3a 20        (example: 
1ec70 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
1ec80 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a  unt()]) do not.*
1ec90 2a 20 20 20 20 20 20 20 20 20 20 63 68 61 6e 67  *          chang
1eca0 65 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  e the error code
1ecb0 20 6f 72 20 6d 65 73 73 61 67 65 20 72 65 74 75   or message retu
1ecc0 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  rned by.**      
1ecd0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72      [sqlite3_err
1ece0 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  code()], [sqlite
1ecf0 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20  3_errmsg()], or 
1ed00 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
1ed10 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  6()]..**.** {H12
1ed20 38 30 39 7d 20 49 6e 74 65 72 66 61 63 65 73 20  809} Interfaces 
1ed30 74 68 61 74 20 61 72 65 20 6e 6f 74 20 61 73 73  that are not ass
1ed40 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 73  ociated with a s
1ed50 70 65 63 69 66 69 63 0a 2a 2a 20 20 20 20 20 20  pecific.**      
1ed60 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
1ed70 6e 6e 65 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70  nnection] (examp
1ed80 6c 65 73 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20  les:.**         
1ed90 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
1eda0 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  f()] or [sqlite3
1edb0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
1edc0 61 63 68 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20  ache()].**      
1edd0 20 20 20 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67      do not chang
1ede0 65 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  e the values ret
1edf0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
1ee00 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72       [sqlite3_er
1ee10 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74  rcode()], [sqlit
1ee20 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72  e3_errmsg()], or
1ee30 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1ee40 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
1ee50 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
1ee60 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
1ee70 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1ee80 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
1ee90 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1eea0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
1eeb0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1eec0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
1eed0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
1eee0 7b 48 31 33 30 30 30 7d 20 3c 48 31 33 30 31 30  {H13000} <H13010
1eef0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
1ef00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ef10 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
1ef20 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
1ef30 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
1ef40 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
1ef50 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
1ef60 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
1ef70 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
1ef80 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
1ef90 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
1efa0 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
1efb0 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
1efc0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
1efd0 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
1efe0 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
1eff0 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
1f000 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
1f010 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
1f020 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
1f030 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
1f040 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1f050 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f060 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
1f070 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
1f080 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
1f090 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
1f0a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
1f0b0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
1f0c0 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
1f0d0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
1f0e0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
1f0f0 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
1f100 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
1f110 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
1f120 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
1f130 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
1f140 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
1f150 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
1f160 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
1f170 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
1f180 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
1f190 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
1f1a0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
1f1b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1f1c0 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
1f1d0 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
1f1e0 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
1f1f0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
1f200 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
1f210 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1f220 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
1f230 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1f240 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
1f250 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
1f260 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
1f270 65 20 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 30  e Limits {H12760
1f280 7d 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20600>.**.**
1f290 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1f2a0 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
1f2b0 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
1f2c0 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
1f2d0 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
1f2e0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
1f2f0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
1f300 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1f310 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
1f320 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1f330 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
1f340 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
1f350 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
1f360 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
1f370 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
1f380 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
1f390 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
1f3a0 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
1f3b0 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
1f3c0 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
1f3d0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
1f3e0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
1f3f0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
1f400 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74  ruct.  The funct
1f410 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1f420 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a  old limit..**.**
1f430 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69   If the new limi
1f440 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
1f450 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
1f460 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
1f470 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74  ** For the limit
1f480 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c   category of SQL
1f490 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68  ITE_LIMIT_XYZ th
1f4a0 65 72 65 20 69 73 20 61 20 68 61 72 64 20 75 70  ere is a hard up
1f4b0 70 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74  per.** bound set
1f4c0 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69   by a compile-ti
1f4d0 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  me C preprocesso
1f4e0 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53 51  r macro named SQ
1f4f0 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a  LITE_MAX_XYZ..**
1f500 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
1f510 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
1f520 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
1f530 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20  ".).** Attempts 
1f540 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
1f550 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
1f560 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
1f570 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
1f580 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
1f590 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74  hard upper limit
1f5a0 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65  ..**.** Run time
1f5b0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
1f5c0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
1f5d0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
1f5e0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
1f5f0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
1f600 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
1f610 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
1f620 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
1f630 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
1f640 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
1f650 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
1f660 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
1f670 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 62  ght be a.** webb
1f680 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
1f690 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
1f6a0 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
1f6b0 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
1f6c0 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
1f6d0 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
1f6e0 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
1f6f0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
1f700 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
1f710 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
1f720 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
1f730 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
1f740 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
1f750 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
1f760 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
1f770 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
1f780 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
1f790 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
1f7a0 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
1f7b0 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
1f7c0 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
1f7d0 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
1f7e0 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
1f7f0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
1f800 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1f810 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
1f820 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
1f830 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
1f840 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
1f850 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1f860 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
1f870 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
1f880 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
1f890 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
1f8a0 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
1f8b0 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
1f8c0 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
1f8d0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1f8e0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
1f8f0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
1f900 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1f910 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36  TS:.**.** {H1276
1f920 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  2} A successful 
1f930 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1f940 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77  _limit(D,C,V)] w
1f950 68 65 72 65 20 56 20 69 73 0a 2a 2a 20 20 20 20  here V is.**    
1f960 20 20 20 20 20 20 70 6f 73 69 74 69 76 65 20 63        positive c
1f970 68 61 6e 67 65 73 20 74 68 65 20 6c 69 6d 69 74  hanges the limit
1f980 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20   on the size of 
1f990 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 74  construct C in t
1f9a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
1f9b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f9c0 69 6f 6e 5d 20 44 20 74 6f 20 74 68 65 20 6c 65  ion] D to the le
1f9d0 73 73 65 72 20 6f 66 20 56 20 61 6e 64 20 74 68  sser of V and th
1f9e0 65 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20  e hard upper.** 
1f9f0 20 20 20 20 20 20 20 20 20 62 6f 75 6e 64 20 6f           bound o
1fa00 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 43 20  n the size of C 
1fa10 74 68 61 74 20 69 73 20 73 65 74 20 61 74 20 63  that is set at c
1fa20 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a  ompile-time..**.
1fa30 2a 2a 20 7b 48 31 32 37 36 36 7d 20 41 20 73 75  ** {H12766} A su
1fa40 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1fa50 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1fa60 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20  D,C,V)] where V 
1fa70 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
1fa80 20 20 20 20 20 20 20 20 6c 65 61 76 65 73 20 74          leaves t
1fa90 68 65 20 73 74 61 74 65 20 6f 66 20 74 68 65 20  he state of the 
1faa0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1fab0 74 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65  tion] D unchange
1fac0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 39  d..**.** {H12769
1fad0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
1fae0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1faf0 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 72 65  limit(D,C,V)] re
1fb00 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
1fb10 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74        value of t
1fb20 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  he limit on the 
1fb30 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63  size of construc
1fb40 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  t C in the.**   
1fb50 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
1fb60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61   connection] D a
1fb70 73 20 69 74 20 77 61 73 20 70 72 69 6f 72 20 74  s it was prior t
1fb80 6f 20 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69  o the call..*/.i
1fb90 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
1fba0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
1fbb0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
1fbc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1fbd0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
1fbe0 43 61 74 65 67 6f 72 69 65 73 20 7b 48 31 32 37  Categories {H127
1fbf0 39 30 7d 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20  90} <H12760>.** 
1fc00 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
1fc10 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69   category} {limi
1fc20 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
1fc30 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
1fc40 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
1fc50 75 73 20 61 73 70 65 63 74 73 20 6f 66 20 61 20  us aspects of a 
1fc60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1fc70 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61  tion].** that ca
1fc80 6e 20 62 65 20 6c 69 6d 69 74 65 64 20 69 6e 20  n be limited in 
1fc90 73 69 7a 65 20 62 79 20 63 61 6c 6c 73 20 74 6f  size by calls to
1fca0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1fcb0 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69  )]..** The meani
1fcc0 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
1fcd0 75 73 20 6c 69 6d 69 74 73 20 61 72 65 20 61 73  us limits are as
1fce0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1fcf0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
1fd00 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
1fd10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1fd20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
1fd30 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
1fd40 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e  OB or table row.
1fd50 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  <dd>.**.** <dt>S
1fd60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
1fd70 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
1fd80 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
1fd90 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
1fda0 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a  statement.</dd>.
1fdb0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1fdc0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
1fdd0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1fde0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1fdf0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
1fe00 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
1fe10 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
1fe20 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43  t set of a SELEC
1fe30 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  T or the maximum
1fe40 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1fe50 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
1fe60 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
1fe70 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
1fe80 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  clause.</dd>.**.
1fe90 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1fea0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
1feb0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1fec0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1fed0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
1fee0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
1fef0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1ff00 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
1ff10 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
1ff20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1ff30 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1ff40 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
1ff50 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
1ff60 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ment.</dd>.**.**
1ff70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1ff80 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
1ff90 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1ffa0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
1ffb0 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
1ffc0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
1ffd0 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
1ffe0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
1fff0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
20000 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
20010 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
20020 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
20030 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
20040 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
20050 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
20060 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
20070 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
20080 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
20090 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
200a0 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64  mber of attached
200b0 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e   databases.</dd>
200c0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
200d0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
200e0 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
200f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
20100 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
20110 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
20120 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f  nt to the LIKE o
20130 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74  r.** GLOB operat
20140 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ors.</dd>.**.** 
20150 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
20160 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
20170 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20180 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
20190 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20  of variables in 
201a0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
201b0 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20   that can.** be 
201c0 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c  bound.</dd>.** <
201d0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
201e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
201f0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
20200 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
20210 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
20220 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
20230 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
20240 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
20250 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
20260 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
20270 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
20280 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
20290 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
202a0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
202b0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
202c0 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
202d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
202e0 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
202f0 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
20300 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
20310 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
20320 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
20330 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
20340 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
20350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
20360 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
20370 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
20380 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
20390 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
203a0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
203b0 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
203c0 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  9../*.** CAPI3RE
203d0 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
203e0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48  SQL Statement {H
203f0 31 33 30 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a  13010} <S10000>.
20400 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
20410 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
20420 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  iler}.**.** To e
20430 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
20440 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
20450 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
20460 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
20470 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
20480 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
20490 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
204a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
204b0 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
204c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
204d0 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
204e0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 63 61 6c 6c   a.** prior call
204f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
20500 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
20510 70 65 6e 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  pen_v2()] or [sq
20520 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
20530 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
20540 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
20550 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
20560 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
20570 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
20580 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
20590 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
205a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
205b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
205c0 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
205d0 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
205e0 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
205f0 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
20600 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20610 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
20620 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  F-16..**.** If t
20630 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
20640 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
20650 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
20660 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
20670 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
20680 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42  erminator. If nB
20690 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
206a0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
206b0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
206c0 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
206d0 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
206e0 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e   When nByte is n
206f0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
20700 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
20710 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
20720 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
20730 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
20740 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
20750 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
20760 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
20770 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
20780 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
20790 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
207a0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
207b0 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
207c0 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
207d0 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
207e0 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
207f0 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
20800 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
20810 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
20820 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
20830 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
20840 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
20850 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
20860 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
20870 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a  nator bytes..**.
20880 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  ** *pzTail is ma
20890 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
208a0 68 65 20 66 69 72 73 74 20 62 79 74 65 20 70 61  he first byte pa
208b0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
208c0 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 73  e.** first SQL s
208d0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
208e0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
208f0 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74  s only compile t
20900 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74 61 74  he first.** stat
20910 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
20920 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
20930 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68  t pointing to wh
20940 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e  at remains.** un
20950 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
20960 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
20970 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
20980 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
20990 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
209a0 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
209b0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
209c0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 49 66 20  e3_step()].  If 
209d0 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
209e0 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
209f0 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49  t.** to NULL.  I
20a00 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
20a10 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
20a20 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
20a30 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
20a40 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
20a50 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
20a60 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
20a70 2a 2a 20 7b 41 31 33 30 31 38 7d 20 54 68 65 20  ** {A13018} The 
20a80 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
20a90 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
20aa0 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
20ab0 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
20ac0 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
20ad0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
20ae0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
20af0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
20b00 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  h it..**.** On s
20b10 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
20b20 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c  OK] is returned,
20b30 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
20b40 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
20b50 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
20b60 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
20b70 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
20b80 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
20b90 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
20ba0 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
20bb0 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
20bc0 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
20bd0 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
20be0 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
20bf0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
20c00 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
20c10 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
20c20 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20  couraged..** In 
20c30 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
20c40 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
20c50 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
20c60 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
20c70 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
20c80 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
20c90 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
20ca0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
20cb0 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
20cc0 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
20cd0 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
20ce0 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
20cf0 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69   a differently i
20d00 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a  n two ways:.**.*
20d10 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
20d20 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
20d30 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
20d40 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
20d50 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
20d60 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
20d70 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
20d80 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
20d90 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
20da0 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
20db0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
20dc0 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
20dd0 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20   run it again.  
20de0 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61  If the schema ha
20df0 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20  s changed in.** 
20e00 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73  a way that makes
20e10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e   the statement n
20e20 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20  o longer valid, 
20e30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20e40 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72   will still.** r
20e50 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43  eturn [SQLITE_SC
20e60 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69  HEMA].  But unli
20e70 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  ke the legacy be
20e80 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f  havior, [SQLITE_
20e90 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f  SCHEMA] is.** no
20ea0 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e  w a fatal error.
20eb0 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74    Calling [sqlit
20ec0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20ed0 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20   again will not 
20ee0 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f  make the.** erro
20ef0 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65  r go away.  Note
20f00 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65  : use [sqlite3_e
20f10 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64  rrmsg()] to find
20f20 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20   the text.** of 
20f30 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f  the parsing erro
20f40 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69  r that results i
20f50 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  n an [SQLITE_SCH
20f60 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20  EMA] return..** 
20f70 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
20f80 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f  .** When an erro
20f90 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
20fa0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
20fb0 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
20fc0 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
20fd0 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
20fe0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
20ff0 6f 64 65 73 5d 2e 20 20 54 68 65 20 6c 65 67 61  odes].  The lega
21000 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
21010 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
21020 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
21030 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
21040 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
21050 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
21060 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64  ** and you would
21070 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
21080 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
21090 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
210a0 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
210b0 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
210c0 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
210d0 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
210e0 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
210f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
21100 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
21110 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
21120 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
21130 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
21140 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a  /li>.** </ol>.**
21150 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
21160 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 31 7d 20 54  **.** {H13011} T
21170 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
21180 61 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  are(db,zSql,...)
21190 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
211a0 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
211b0 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e  re_v2(db,zSql,..
211c0 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69  .)] interfaces i
211d0 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
211e0 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69 6e           text in
211f0 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61   their zSql para
21200 6d 65 74 65 72 20 61 73 20 55 54 46 2d 38 2e 0a  meter as UTF-8..
21210 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 32 7d 20 54  **.** {H13012} T
21220 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
21230 61 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e  are16(db,zSql,..
21240 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  .)] and.**      
21250 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
21260 70 61 72 65 31 36 5f 76 32 28 64 62 2c 7a 53 71  pare16_v2(db,zSq
21270 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  l,...)] interfac
21280 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  es interpret the
21290 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65 78  .**          tex
212a0 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20  t in their zSql 
212b0 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54 46  parameter as UTF
212c0 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
212d0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
212e0 0a 2a 2a 20 7b 48 31 33 30 31 33 7d 20 49 66 20  .** {H13013} If 
212f0 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
21300 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  nt to [sqlite3_p
21310 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
21320 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a  l,nByte,...)].**
21330 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74            and it
21340 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6c 65  s variants is le
21350 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ss than zero, th
21360 65 20 53 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a  e SQL text is.**
21370 20 20 20 20 20 20 20 20 20 20 72 65 61 64 20 66            read f
21380 72 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 64  rom zSql is read
21390 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
213a0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
213b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 34 7d  ..**.** {H13014}
213c0 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
213d0 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
213e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
213f0 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29  ,zSql,nByte,...)
21400 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  ].**          an
21410 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 69  d its variants i
21420 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
21430 74 68 65 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79  then at most nBy
21440 74 65 73 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20  tes bytes of.** 
21450 20 20 20 20 20 20 20 20 20 53 51 4c 20 74 65 78           SQL tex
21460 74 20 69 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  t is read from z
21470 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  Sql..**.** {H130
21480 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f  15} In [sqlite3_
21490 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
214a0 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20  ql,N,P,pzTail)] 
214b0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
214c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20  .**          if 
214d0 74 68 65 20 7a 53 71 6c 20 69 6e 70 75 74 20 74  the zSql input t
214e0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72  ext contains mor
214f0 65 20 74 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73  e than one SQL s
21500 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20  tatement.**     
21510 20 20 20 20 20 61 6e 64 20 70 7a 54 61 69 6c 20       and pzTail 
21520 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
21530 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
21540 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
21550 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  e.**          fi
21560 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68  rst byte past th
21570 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
21580 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
21590 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20   in zSql..**    
215a0 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74        <todo>What
215b0 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f   does *pzTail po
215c0 69 6e 74 20 74 6f 20 69 66 20 74 68 65 72 65 20  int to if there 
215d0 69 73 20 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74  is one statement
215e0 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b  ?</todo>.**.** {
215f0 48 31 33 30 31 36 7d 20 41 20 73 75 63 63 65 73  H13016} A succes
21600 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
21610 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21620 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d  (db,zSql,N,ppStm
21630 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  t,...)].**      
21640 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74      or one of it
21650 73 20 76 61 72 69 61 6e 74 73 20 77 72 69 74 65  s variants write
21660 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61  s into *ppStmt a
21670 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
21680 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  w.**          [p
21690 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
216a0 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  t] or a pointer 
216b0 74 6f 20 4e 55 4c 4c 20 69 66 20 7a 53 71 6c 20  to NULL if zSql 
216c0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20  contains.**     
216d0 20 20 20 20 20 6e 6f 74 68 69 6e 67 20 6f 74 68       nothing oth
216e0 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61  er than whitespa
216f0 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 0a  ce or comments..
21700 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 39 7d 20 54  **.** {H13019} T
21710 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
21720 61 72 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  are_v2()] interf
21730 61 63 65 20 61 6e 64 20 69 74 73 20 76 61 72 69  ace and its vari
21740 61 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20  ants return.**  
21750 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
21760 4f 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72 6f 70  OK] or an approp
21770 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
21780 65 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e  e] upon failure.
21790 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 32 31 7d 20  .**.** {H13021} 
217a0 42 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  Before [sqlite3_
217b0 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c  prepare(db,zSql,
217c0 6e 42 79 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54  nByte,ppStmt,pzT
217d0 61 69 6c 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20  ail)] or its.** 
217e0 20 20 20 20 20 20 20 20 20 76 61 72 69 61 6e 74           variant
217f0 73 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  s returns an err
21800 6f 72 20 28 61 6e 79 20 76 61 6c 75 65 20 6f 74  or (any value ot
21810 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
21820 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20 20 20 20 20 20  _OK]),.**       
21830 20 20 20 74 68 65 79 20 66 69 72 73 74 20 73 65     they first se
21840 74 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c  t *ppStmt to NUL
21850 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
21860 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
21870 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
21880 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
21890 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
218a0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
218b0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
218c0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
218d0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
218e0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
218f0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
21900 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
21910 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
21920 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
21930 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
21940 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
21950 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
21960 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
21970 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
21980 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
21990 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
219a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
219b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
219c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
219d0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
219e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
219f0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
21a00 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
21a10 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
21a20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
21a30 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
21a40 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
21a50 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
21a60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
21a70 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
21a80 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
21a90 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
21aa0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
21ab0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
21ac0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
21ad0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
21ae0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
21af0 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  re16(.  sqlite3 
21b00 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
21b10 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
21b20 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
21b30 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
21b40 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
21b50 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
21b60 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
21b70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
21b80 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
21b90 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
21ba0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
21bb0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
21bc0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
21bd0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
21be0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
21bf0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
21c00 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
21c10 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
21c20 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
21c30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
21c40 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
21c50 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
21c60 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
21c70 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
21c80 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
21c90 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
21ca0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
21cb0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
21cc0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
21cd0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
21ce0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
21cf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
21d00 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
21d10 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
21d20 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
21d30 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
21d40 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
21d50 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
21d60 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
21d70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
21d80 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
21d90 65 6e 74 20 53 51 4c 20 7b 48 31 33 31 30 30 7d  ent SQL {H13100}
21da0 20 3c 48 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H13000>.**.** 
21db0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
21dc0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
21dd0 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
21de0 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
21df0 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
21e00 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
21e10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21e20 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
21e30 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
21e40 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
21e50 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
21e60 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
21e70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
21e80 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  6_v2()]..**.** I
21e90 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
21ea0 20 7b 48 31 33 31 30 31 7d 20 49 66 20 74 68 65   {H13101} If the
21eb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21ec0 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20  ment] passed as 
21ed0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
21ee0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
21ef0 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20  ite3_sql()] was 
21f00 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
21f10 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
21f20 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a  repare_v2()] or.
21f30 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
21f40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
21f50 32 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69  2()], then [sqli
21f60 74 65 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 72  te3_sql()] retur
21f70 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
21f80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
21f90 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
21fa0 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
21fb0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
21fc0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  g.**          of
21fd0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 53 51   the original SQ
21fe0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  L statement..**.
21ff0 2a 2a 20 7b 48 31 33 31 30 32 7d 20 49 66 20 74  ** {H13102} If t
22000 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
22010 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61  tement] passed a
22020 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
22030 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
22040 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61  qlite3_sql()] wa
22050 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  s compiled using
22060 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
22070 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a  _prepare()] or.*
22080 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
22090 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
220a0 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  , then [sqlite3_
220b0 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 20 61  sql()] returns a
220c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
220d0 2a 0a 2a 2a 20 7b 48 31 33 31 30 33 7d 20 54 68  *.** {H13103} Th
220e0 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
220f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 71  d by [sqlite3_sq
22100 6c 28 53 29 5d 20 69 73 20 76 61 6c 69 64 20 75  l(S)] is valid u
22110 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20  ntil the.**     
22120 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
22130 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 64  tatement] S is d
22140 65 6c 65 74 65 64 20 75 73 69 6e 67 20 5b 73 71  eleted using [sq
22150 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
22160 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
22170 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
22180 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
22190 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
221a0 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
221b0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
221c0 6a 65 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53  ject {H15000} <S
221d0 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  20200>.** KEYWOR
221e0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
221f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
22200 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
22210 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
22220 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
22230 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
22240 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
22250 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
22260 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
22270 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
22280 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
22290 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
222a0 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
222b0 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
222c0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
222d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
222e0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
222f0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
22300 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
22310 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
22320 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
22330 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
22340 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
22350 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
22360 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
22370 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
22380 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
22390 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
223a0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
223b0 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
223c0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
223d0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
223e0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
223f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
22400 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
22410 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
22420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
22430 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
22440 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
22450 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
22460 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
22470 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
22480 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
22490 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
224a0 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
224b0 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
224c0 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
224d0 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c  eld.  A internal
224e0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
224f0 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
22500 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
22510 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
22520 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
22530 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
22540 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
22550 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
22560 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
22570 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
22580 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
22590 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
225a0 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
225b0 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
225c0 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
225d0 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
225e0 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
225f0 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
22600 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
22610 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
22620 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
22630 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
22640 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
22650 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
22660 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
22670 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
22680 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
22690 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
226a0 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
226b0 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
226c0 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
226d0 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
226e0 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
226f0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
22700 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
22710 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
22720 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
22730 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65  on between betwe
22740 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
22750 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
22760 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
22770 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
22780 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
22790 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
227a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
227b0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
227c0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
227d0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
227e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
227f0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
22800 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
22810 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
22820 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cted..** The sql
22830 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
22840 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
22850 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
22860 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
22870 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
22880 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
22890 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
228a0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
228b0 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
228c0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
228d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
228e0 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
228f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
22900 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
22910 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
22920 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
22930 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
22940 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
22950 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
22960 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
22970 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
22980 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
22990 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
229a0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
229b0 63 74 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30  ct {H16001} <S20
229c0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  200>.**.** The c
229d0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
229e0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
229f0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
22a00 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
22a10 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
22a20 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74  ct.  A pointer t
22a30 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
22a40 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
22a50 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
22a60 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
22a70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
22a80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
22a90 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
22aa0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
22ab0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
22ac0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
22ad0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
22ae0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
22af0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
22b00 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
22b10 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
22b20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
22b30 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
22b40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
22b50 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
22b60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
22b70 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
22b80 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
22b90 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
22ba0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
22bb0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
22bc0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
22bd0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
22be0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
22bf0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
22c00 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
22c10 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
22c20 73 20 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33  s {H13500} <S703
22c30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
22c40 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
22c50 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
22c60 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
22c70 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
22c80 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
22c90 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
22ca0 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
22cb0 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
22cc0 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72  * In the SQL str
22cd0 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73  ings input to [s
22ce0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22cf0 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
22d00 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
22d10 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
22d20 65 64 20 62 79 20 61 20 70 61 72 61 6d 65 74 65  ed by a paramete
22d30 72 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73  r in one of thes
22d40 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c  e forms:.**.** <
22d50 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
22d60 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
22d70 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
22d80 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
22d90 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
22da0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70 61 72  **.** In the par
22db0 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73 68 6f  ameter forms sho
22dc0 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20  wn above NNN is 
22dd0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
22de0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69  al,.** and VVV i
22df0 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72  s an alpha-numer
22e00 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  ic parameter nam
22e10 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6f 66  e. The values of
22e20 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
22e30 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
22e40 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
22e50 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
22e60 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
22e70 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
22e80 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
22e90 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
22ea0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
22eb0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
22ec0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
22ed0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
22ee0 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
22ef0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
22f00 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
22f10 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
22f20 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
22f30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
22f40 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
22f50 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nts..**.** The s
22f60 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
22f70 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
22f80 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
22f90 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54   to be set..** T
22fa0 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
22fb0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
22fc0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 57 68   index of 1.  Wh
22fd0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
22fe0 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
22ff0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
23000 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
23010 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
23020 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
23030 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
23040 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
23050 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
23060 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
23070 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
23080 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
23090 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
230a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
230b0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
230c0 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 54  I if desired.  T
230d0 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
230e0 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
230f0 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
23100 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e  f NNN..** The NN
23110 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
23120 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
23130 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
23140 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
23150 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
23160 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
23170 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
23180 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  999)..**.** The 
23190 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
231a0 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
231b0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
231c0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  eter..**.** In t
231d0 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
231e0 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
231f0 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
23200 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
23210 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
23220 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
23230 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
23240 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
23250 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
23260 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
23270 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
23280 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
23290 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ters..** If the 
232a0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
232b0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
232c0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
232d0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
232e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
232f0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
23300 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
23310 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74  ..**.** The fift
23320 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
23330 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
23340 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
23350 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
23360 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
23370 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
23380 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
23390 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
233a0 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
233b0 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
233c0 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
233d0 20 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72   If the fifth ar
233e0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
233f0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
23400 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
23410 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
23420 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
23430 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
23440 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
23450 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
23460 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
23470 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74  e freed..** If t
23480 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
23490 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
234a0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
234b0 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
234c0 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
234d0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
234e0 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
234f0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
23500 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
23510 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
23520 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  turns..**.** The
23530 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
23540 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
23550 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
23560 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
23570 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
23580 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f   zeroes.  A zero
23590 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
235a0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
235b0 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
235c0 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
235d0 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
235e0 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
235f0 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
23600 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
23610 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
23620 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
23630 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
23640 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
23650 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
23660 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
23670 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
23680 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
23690 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69 76 65  s..** A negative
236a0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
236b0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
236c0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
236d0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   BLOB..**.** The
236e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
236f0 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  ) routines must 
23700 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 0a  be called after.
23710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
23720 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64 20 69  are_v2()] (and i
23730 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f 72 20  ts variants) or 
23740 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
23750 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20  ] and.** before 
23760 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23770 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20 61 72  ..** Bindings ar
23780 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
23790 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
237a0 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
237b0 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  ** Unbound param
237c0 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
237d0 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
237e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
237f0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
23800 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
23810 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20 63 6f  s or an error co
23820 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e  de if.** anythin
23830 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b  g goes wrong.  [
23840 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
23850 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
23860 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
23870 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
23880 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f  nge.  [SQLITE_NO
23890 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
238a0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
238b0 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  ls..** [SQLITE_M
238c0 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62 65 20  ISUSE] might be 
238d0 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 73  returned if thes
238e0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
238f0 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69  alled on a.** vi
23900 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 74 68  rtual machine th
23910 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e 67 20  at is the wrong 
23920 73 74 61 74 65 20 6f 72 20 77 68 69 63 68 20 68  state or which h
23930 61 73 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  as already been 
23940 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65  finalized..** De
23950 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73  tection of misus
23960 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e  e is unreliable.
23970 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73    Applications s
23980 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64  hould not depend
23990 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49  .** on SQLITE_MI
239a0 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20 20 53  SUSE returns.  S
239b0 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69 73 20  QLITE_MISUSE is 
239c0 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e 64 69  intended to indi
239d0 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69  cate a.** a logi
239e0 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 61  c error in the a
239f0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46 75 74  pplication.  Fut
23a00 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
23a10 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
23a20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74 68 61  panic rather tha
23a30 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  n return SQLITE_
23a40 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65  MISUSE..**.** Se
23a50 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
23a60 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
23a70 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
23a80 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
23a90 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
23aa0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
23ab0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
23ac0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
23ad0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
23ae0 35 30 36 7d 20 54 68 65 20 5b 53 51 4c 20 73 74  506} The [SQL st
23af0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
23b00 5d 20 72 65 63 6f 67 6e 69 7a 65 73 20 74 6f 6b  ] recognizes tok
23b10 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 73  ens of the forms
23b20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 22 3f 22  .**          "?"
23b30 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22  , "?NNN", "$VVV"
23b40 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64 20 22 40  , ":VVV", and "@
23b50 56 56 56 22 20 61 73 20 53 51 4c 20 70 61 72 61  VVV" as SQL para
23b60 6d 65 74 65 72 73 2c 0a 2a 2a 20 20 20 20 20 20  meters,.**      
23b70 20 20 20 20 77 68 65 72 65 20 4e 4e 4e 20 69 73      where NNN is
23b80 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66   any sequence of
23b90 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 64 69 67   one or more dig
23ba0 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
23bb0 61 6e 64 20 77 68 65 72 65 20 56 56 56 20 69 73  and where VVV is
23bc0 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20 6f 66   any sequence of
23bd0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 61 6c 70   one or more alp
23be0 68 61 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20  hanumeric.**    
23bf0 20 20 20 20 20 20 63 68 61 72 61 63 74 65 72 73        characters
23c00 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61   or "::" optiona
23c10 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  lly followed by 
23c20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  a string contain
23c30 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
23c40 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20 63 6f  no spaces and co
23c50 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 70  ntained within p
23c60 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a  arentheses..**.*
23c70 2a 20 7b 48 31 33 35 30 39 7d 20 54 68 65 20 69  * {H13509} The i
23c80 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f 66 20  nitial value of 
23c90 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
23ca0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
23cb0 7b 48 31 33 35 31 32 7d 20 54 68 65 20 69 6e 64  {H13512} The ind
23cc0 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c  ex of an "?" SQL
23cd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
23ce0 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
23cf0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 61  e.**          la
23d00 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 53  rgest index of S
23d10 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
23d20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31 20 69  the left, or 1 i
23d30 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
23d40 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c 65 66  e "?" is the lef
23d50 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
23d60 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ter..**.** {H135
23d70 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  15} The index of
23d80 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70   an "?NNN" SQL p
23d90 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
23da0 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a  integer NNN..**.
23db0 2a 2a 20 7b 48 31 33 35 31 38 7d 20 54 68 65 20  ** {H13518} The 
23dc0 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a 56 56  index of an ":VV
23dd0 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72 20 22  V", "$VVV", or "
23de0 40 56 56 56 22 20 53 51 4c 20 70 61 72 61 6d 65  @VVV" SQL parame
23df0 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ter is.**       
23e00 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20 74     the same as t
23e10 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65 66 74  he index of left
23e20 6d 6f 73 74 20 6f 63 63 75 72 72 65 6e 63 65 73  most occurrences
23e30 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
23e40 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
23e50 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20  er, or one more 
23e60 74 68 61 6e 20 74 68 65 20 6c 61 72 67 65 73 74  than the largest
23e70 20 69 6e 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a   index over all.
23e80 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61  **          para
23e90 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 6c 65  meters to the le
23ea0 66 74 20 69 66 20 74 68 69 73 20 69 73 20 74 68  ft if this is th
23eb0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
23ec0 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ce.**          o
23ed0 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
23ee0 2c 20 6f 72 20 31 20 69 66 20 74 68 69 73 20 69  , or 1 if this i
23ef0 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 70  s the leftmost p
23f00 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
23f10 7b 48 31 33 35 32 31 7d 20 54 68 65 20 5b 53 51  {H13521} The [SQ
23f20 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
23f30 69 6c 65 72 5d 20 66 61 69 6c 73 20 77 69 74 68  iler] fails with
23f40 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47   an [SQLITE_RANG
23f50 45 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  E].**          e
23f60 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e 64 65  rror if the inde
23f70 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
23f80 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
23f90 61 6e 20 31 0a 2a 2a 20 20 20 20 20 20 20 20 20  an 1.**         
23fa0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
23fb0 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
23fc0 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52  e SQLITE_MAX_VAR
23fd0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20  IABLE_NUMBER.** 
23fe0 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
23ff0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32  er..**.** {H1352
24000 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  4} Calls to [sql
24010 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
24020 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c   sqlite3_bind(S,
24030 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  N,V,...)].**    
24040 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 20        associate 
24050 74 68 65 20 76 61 6c 75 65 20 56 20 77 69 74 68  the value V with
24060 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74   all SQL paramet
24070 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a  ers having an.**
24080 20 20 20 20 20 20 20 20 20 20 69 6e 64 65 78 20            index 
24090 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70 72 65  of N in the [pre
240a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
240b0 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32   S..**.** {H1352
240c0 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  7} Calls to [sql
240d0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
240e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c   sqlite3_bind(S,
240f0 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  N,...)].**      
24100 20 20 20 20 6f 76 65 72 72 69 64 65 20 70 72 69      override pri
24110 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20 74 68  or calls with th
24120 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20 6f 66  e same values of
24130 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20   S and N..**.** 
24140 7b 48 31 33 35 33 30 7d 20 42 69 6e 64 69 6e 67  {H13530} Binding
24150 73 20 65 73 74 61 62 6c 69 73 68 65 64 20 62 79  s established by
24160 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
24170 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  ext | sqlite3_bi
24180 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  nd(S,...)].**   
24190 20 20 20 20 20 20 20 70 65 72 73 69 73 74 20 61         persist a
241a0 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b  cross calls to [
241b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
241c0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 33  ]..**.** {H13533
241d0 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
241e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
241f0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
24200 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
24210 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
24220 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
24230 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
24240 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
24250 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65  N,V,L,D)] SQLite
24260 20 62 69 6e 64 73 20 74 68 65 20 66 69 72 73 74   binds the first
24270 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62   L.**          b
24280 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ytes of the BLOB
24290 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69 6e 74   or string point
242a0 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68 65 6e  ed to by V, when
242b0 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   L.**          i
242c0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
242d0 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 36 7d 20 49  **.** {H13536} I
242e0 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
242f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
24300 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20  N,V,L,D)] or.** 
24310 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
24320 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
24330 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65  N,V,L,D)] SQLite
24340 20 62 69 6e 64 73 20 63 68 61 72 61 63 74 65 72   binds character
24350 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  s.**          fr
24360 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74 68 65  om V through the
24370 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
24380 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69 73 20  acter when L is 
24390 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
243a0 7b 48 31 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c  {H13539} In call
243b0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
243c0 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c  nd_blob(S,N,V,L,
243d0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
243e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
243f0 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  ext(S,N,V,L,D)],
24400 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
24410 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
24420 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  xt16(S,N,V,L,D)]
24430 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73   when D is the s
24440 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20  pecial.**       
24450 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c     constant [SQL
24460 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c  ITE_STATIC], SQL
24470 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
24480 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20   the value V.** 
24490 20 20 20 20 20 20 20 20 20 69 73 20 68 65 6c 64           is held
244a0 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d 61 6e   in static unman
244b0 61 67 65 64 20 73 70 61 63 65 20 74 68 61 74 20  aged space that 
244c0 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a  will not change.
244d0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75 72 69  **          duri
244e0 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
244f0 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a  of the binding..
24500 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 32 7d 20 49  **.** {H13542} I
24510 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
24520 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
24530 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
24540 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
24550 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
24560 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
24570 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
24580 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
24590 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73  ,L,D)] when D is
245a0 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20   the special.** 
245b0 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e           constan
245c0 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  t [SQLITE_TRANSI
245d0 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e  ENT], the routin
245e0 65 20 6d 61 6b 65 73 20 61 0a 2a 2a 20 20 20 20  e makes a.**    
245f0 20 20 20 20 20 20 70 72 69 76 61 74 65 20 63 6f        private co
24600 70 79 20 6f 66 20 74 68 65 20 76 61 6c 75 65 20  py of the value 
24610 56 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  V before it retu
24620 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  rns..**.** {H135
24630 34 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  45} In calls to 
24640 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
24650 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a  ob(S,N,V,L,D)],.
24660 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
24670 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
24680 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a  ,N,V,L,D)], or.*
24690 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
246a0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
246b0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e  S,N,V,L,D)] when
246c0 20 44 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20   D is a pointer 
246d0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  to.**          a
246e0 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
246f0 65 20 69 6e 76 6f 6b 65 73 20 74 68 61 74 20 66  e invokes that f
24700 75 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73 74 72  unction to destr
24710 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  oy the.**       
24720 20 20 20 76 61 6c 75 65 20 56 20 61 66 74 65 72     value V after
24730 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
24740 20 75 73 69 6e 67 20 74 68 65 20 76 61 6c 75 65   using the value
24750 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34   V..**.** {H1354
24760 38 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  8} In calls to [
24770 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
24780 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20  oblob(S,N,V,L)] 
24790 74 68 65 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a  the value bound.
247a0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 61  **          is a
247b0 20 42 4c 4f 42 20 6f 66 20 4c 20 62 79 74 65 73   BLOB of L bytes
247c0 2c 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  , or a zero-leng
247d0 74 68 20 42 4c 4f 42 20 69 66 20 4c 20 69 73 20  th BLOB if L is 
247e0 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
247f0 7b 48 31 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c  {H13551} In call
24800 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
24810 6e 64 5f 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d  nd_value(S,N,V)]
24820 20 74 68 65 20 56 20 61 72 67 75 6d 65 6e 74 20   the V argument 
24830 6d 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  may.**          
24840 62 65 20 65 69 74 68 65 72 20 61 20 5b 70 72 6f  be either a [pro
24850 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
24860 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20  alue] object or 
24870 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
24880 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
24890 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
248a0 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
248b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
248c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
248d0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
248e0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
248f0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
24900 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c  _bind_double(sql
24910 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
24920 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71   double);.int sq
24930 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73  lite3_bind_int(s
24940 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24950 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  t, int);.int sql
24960 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
24970 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
24980 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
24990 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  4);.int sqlite3_
249a0 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
249b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69  3_stmt*, int);.i
249c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
249d0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
249e0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
249f0 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  har*, int n, voi
24a00 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
24a10 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
24a20 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
24a30 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
24a40 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
24a50 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
24a60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
24a70 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
24a80 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
24a90 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
24aa0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
24ab0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
24ac0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
24ad0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
24ae0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
24af0 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 20 7b  SQL Parameters {
24b00 48 31 33 36 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13600} <S70300>
24b10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
24b20 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
24b30 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
24b40 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
24b50 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
24b60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24b70 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
24b80 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
24b90 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
24ba0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
24bb0 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
24bc0 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
24bd0 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
24be0 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
24bf0 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
24c00 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
24c10 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
24c20 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
24c30 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
24c40 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
24c50 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
24c60 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
24c70 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
24c80 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
24c90 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
24ca0 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
24cb0 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
24cc0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
24cd0 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
24ce0 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
24cf0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
24d00 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  NN are used,.** 
24d10 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
24d20 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a  s in the list..*
24d30 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
24d40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
24d50 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
24d60 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
24d70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
24d80 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
24d90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
24da0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
24db0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
24dc0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 30 31 7d  :.**.** {H13601}
24dd0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   The [sqlite3_bi
24de0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
24df0 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  nt(S)] interface
24e00 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
24e10 20 20 20 20 20 74 68 65 20 6c 61 72 67 65 73 74       the largest
24e20 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20 53 51   index of all SQ
24e30 4c 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  L parameters in 
24e40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24e50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24e60 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69 66 20  ent] S, or 0 if 
24e70 53 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  S contains no SQ
24e80 4c 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  L parameters..*/
24e90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
24ea0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
24eb0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
24ec0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24ed0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
24ee0 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48 31 33  t Parameter {H13
24ef0 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  620} <S70300>.**
24f00 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
24f10 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
24f20 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f  er to the name o
24f30 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53  f the n-th.** [S
24f40 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
24f50 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
24f60 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20  tement]..** SQL 
24f70 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
24f80 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
24f90 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
24fa0 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
24fb0 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
24fc0 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
24fd0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
24fe0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
24ff0 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
25000 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
25010 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
25020 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
25030 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
25040 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
25050 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
25060 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73 20 6f  .** Parameters o
25070 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
25080 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
25090 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
250a0 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
250b0 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72 65 64  re also referred
250c0 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75   to as "anonymou
250d0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
250e0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 68  *.** The first h
250f0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
25100 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
25110 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66   not 0..**.** If
25120 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69 73 20   the value n is 
25130 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
25140 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61 72 61  if the n-th para
25150 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
25160 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
25170 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
25180 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
25190 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
251a0 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
251b0 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
251c0 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
251d0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
251e0 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
251f0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
25200 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
25210 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
25220 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
25230 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
25240 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
25250 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
25260 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
25270 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
25280 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
25290 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
252a0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a  ter_index()]..**
252b0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
252c0 2a 2a 0a 2a 2a 20 7b 48 31 33 36 32 31 7d 20 54  **.** {H13621} T
252d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
252e0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
252f0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
25300 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
25310 20 20 20 20 61 20 55 54 46 2d 38 20 72 65 6e 64      a UTF-8 rend
25320 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d  ering of the nam
25330 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  e of the SQL par
25340 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20  ameter in.**    
25350 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
25360 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
25370 20 68 61 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c   having index N,
25380 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
25390 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73  NULL if there is
253a0 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65   no SQL paramete
253b0 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 6f  r with index N o
253c0 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  r if the.**     
253d0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 77       parameter w
253e0 69 74 68 20 69 6e 64 65 78 20 4e 20 69 73 20 61  ith index N is a
253f0 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61  n anonymous para
25400 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f  meter "?"..*/.co
25410 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
25420 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
25430 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
25440 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
25450 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
25460 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
25470 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
25480 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 53 37 30  me {H13640} <S70
25490 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  300>.**.** Retur
254a0 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
254b0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
254c0 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
254d0 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61   The.** index va
254e0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
254f0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
25500 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
25510 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
25520 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25530 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
25540 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  ].  A zero.** is
25550 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
25560 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
25570 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68  er is found.  Th
25580 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
25590 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
255a0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
255b0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
255c0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
255d0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
255e0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
255f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25600 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
25610 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
25620 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
25630 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
25640 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
25650 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
25660 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
25670 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25680 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
25690 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
256a0 2a 0a 2a 2a 20 7b 48 31 33 36 34 31 7d 20 54 68  *.** {H13641} Th
256b0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
256c0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
256d0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
256e0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
256f0 20 20 20 20 74 68 65 20 69 6e 64 65 78 20 6f 66      the index of
25700 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
25710 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
25720 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20  statement].**   
25730 20 20 20 20 20 20 20 53 20 77 68 6f 73 65 20 6e         S whose n
25740 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68 65 20  ame matches the 
25750 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20  UTF-8 string N, 
25760 6f 72 20 30 20 69 66 20 74 68 65 72 65 20 69 73  or 0 if there is
25770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20  .**          no 
25780 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71  match..*/.int sq
25790 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
257a0 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
257b0 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
257c0 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
257d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
257e0 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
257f0 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
25800 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 36 36  Statement {H1366
25810 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
25820 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68  * Contrary to th
25830 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
25840 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
25850 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
25860 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
25870 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
25880 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
25890 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
258a0 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68  ment]..** Use th
258b0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
258c0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
258d0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
258e0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
258f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 36 31  S:.**.** {H13661
25900 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
25910 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 53 29  lear_bindings(S)
25920 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
25930 74 73 20 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20  ts all SQL.**   
25940 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
25950 20 62 69 6e 64 69 6e 67 73 20 69 6e 20 74 68 65   bindings in the
25960 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25970 6d 65 6e 74 5d 20 53 20 62 61 63 6b 20 74 6f 20  ment] S back to 
25980 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
25990 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
259a0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
259b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
259c0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
259d0 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
259e0 6c 74 20 53 65 74 20 7b 48 31 33 37 31 30 7d 20  lt Set {H13710} 
259f0 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52  <S10700>.**.** R
25a00 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
25a10 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
25a20 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
25a30 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
25a40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25a50 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75 74  ment]. This rout
25a60 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
25a70 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
25a80 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
25a90 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
25aa0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
25ab0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
25ac0 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  )..**.** INVARIA
25ad0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  NTS:.**.** {H137
25ae0 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
25af0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29  _column_count(S)
25b00 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
25b10 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
25b20 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  f.**          co
25b30 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
25b40 75 6c 74 20 73 65 74 20 67 65 6e 65 72 61 74 65  ult set generate
25b50 64 20 62 79 20 74 68 65 20 5b 70 72 65 70 61 72  d by the [prepar
25b60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c  ed statement] S,
25b70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
25b80 30 20 69 66 20 53 20 64 6f 65 73 20 6e 6f 74 20  0 if S does not 
25b90 67 65 6e 65 72 61 74 65 20 61 20 72 65 73 75 6c  generate a resul
25ba0 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  t set..*/.int sq
25bb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
25bc0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
25bd0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
25be0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
25bf0 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
25c00 6c 74 20 53 65 74 20 7b 48 31 33 37 32 30 7d 20  lt Set {H13720} 
25c10 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10700>.**.** T
25c20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
25c30 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
25c40 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
25c50 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
25c60 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
25c70 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
25c80 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 65   statement.  The
25c90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25ca0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
25cb0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
25cc0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
25cd0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
25ce0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
25cf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
25d00 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
25d10 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
25d20 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
25d30 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
25d40 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
25d50 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
25d60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25d70 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
25d80 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
25d90 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68 65 20   statement. The 
25da0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
25db0 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
25dc0 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 6c  n number.  The l
25dd0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
25de0 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
25df0 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
25e00 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
25e10 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
25e20 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
25e30 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
25e40 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
25e50 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
25e60 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
25e70 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
25e80 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
25e90 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
25ea0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
25eb0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
25ec0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  olumn..**.** If 
25ed0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
25ee0 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
25ef0 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
25f00 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
25f10 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
25f20 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
25f30 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
25f40 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
25f50 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
25f60 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
25f70 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** The name of a
25f80 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
25f90 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
25fa0 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
25fb0 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
25fc0 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
25fd0 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
25fe0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
25ff0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
26000 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
26010 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
26020 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
26030 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
26040 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
26050 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
26060 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
26070 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 31 7d 20  .**.** {H13721} 
26080 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  A successful inv
26090 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  ocation of the [
260a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
260b0 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20  ame(S,N)].**    
260c0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
260d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65  returns the name
260e0 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   of the Nth colu
260f0 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a  mn (where 0 is.*
26100 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6c  *          the l
26110 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20  eftmost column) 
26120 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74 20 73  for the result s
26130 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  et of the.**    
26140 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
26150 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20  statement] S as 
26160 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
26170 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  d UTF-8 string..
26180 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 33 7d 20 41  **.** {H13723} A
26190 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
261a0 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  cation of the [s
261b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
261c0 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20  me16(S,N)].**   
261d0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
261e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61 6d   returns the nam
261f0 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  e of the Nth col
26200 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73 0a  umn (where 0 is.
26210 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
26220 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29  leftmost column)
26230 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74 20   for the result 
26240 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  set of the.**   
26250 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
26260 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 73   statement] S as
26270 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
26280 65 64 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ed UTF-16 string
26290 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
262a0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
262b0 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  order..**.** {H1
262c0 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  3724} The [sqlit
262d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
262e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
262f0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a  olumn_name16()].
26300 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
26310 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61 20  rfaces return a 
26320 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
26330 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c 65 20  they are unable 
26340 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  to.**          a
26350 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
26360 6f 20 68 6f 6c 64 20 74 68 65 69 72 20 6e 6f 72  o hold their nor
26370 6d 61 6c 20 72 65 74 75 72 6e 20 73 74 72 69 6e  mal return strin
26380 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32  gs..**.** {H1372
26390 35 7d 20 49 66 20 74 68 65 20 4e 20 70 61 72 61  5} If the N para
263a0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
263b0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c  3_column_name(S,
263c0 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  N)] or.**       
263d0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
263e0 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  mn_name16(S,N)] 
263f0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
26400 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   then the.**    
26410 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
26420 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70   return a NULL p
26430 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ointer..**.** {H
26440 31 33 37 32 36 7d 20 54 68 65 20 73 74 72 69 6e  13726} The strin
26450 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  gs returned by [
26460 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
26470 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a  ame(S,N)] and.**
26480 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
26490 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
264a0 28 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c 69 64  (S,N)] are valid
264b0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a   until the next.
264c0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
264d0 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75 74 69   to either routi
264e0 6e 65 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ne with the same
264f0 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d 65 74   S and N paramet
26500 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
26510 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
26520 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
26530 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  s called..**.** 
26540 7b 48 31 33 37 32 37 7d 20 57 68 65 6e 20 61 20  {H13727} When a 
26550 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
26560 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
26570 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a  ement contains.*
26580 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 41 53  *          an AS
26590 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6e 61 6d   clause, the nam
265a0 65 20 6f 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e  e of that column
265b0 20 69 73 20 74 68 65 20 69 64 65 6e 74 69 66 69   is the identifi
265c0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
265d0 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66 20 74  o the right of t
265e0 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a  he AS keyword..*
265f0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
26600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
26610 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
26620 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76   int N);.const v
26630 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
26640 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  umn_name16(sqlit
26650 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
26660 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26670 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74  F: Source Of Dat
26680 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73  a In A Query Res
26690 75 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c 53 31  ult {H13740} <S1
266a0 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0700>.**.** Thes
266b0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
266c0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
266d0 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c  termine what col
266e0 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74  umn of what.** t
266f0 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64 61  able in which da
26700 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74 20  tabase a result 
26710 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
26720 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72  atement comes fr
26730 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  om..** The name 
26740 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
26750 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75  or table or colu
26760 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e  mn can be return
26770 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20  ed as.** either 
26780 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  a UTF-8 or UTF-1
26790 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 5f  6 string.  The _
267a0 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
267b0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
267c0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
267d0 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
267e0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
267f0 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
26800 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
26810 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
26820 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
26830 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
26840 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
26850 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
26860 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
26870 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
26880 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
26890 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
268a0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
268b0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
268c0 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
268d0 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
268e0 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  oding..**.** The
268f0 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
26900 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
26910 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
26920 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
26930 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
26940 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54   column..**.** T
26950 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
26960 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69  t to the followi
26970 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20 5b 70  ng calls is a [p
26980 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26990 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  t]..** These fun
269a0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
269b0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
269c0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
269d0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
269e0 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
269f0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
26a00 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
26a10 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ment..**.** If t
26a20 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
26a30 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
26a40 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
26a50 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
26a60 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
26a70 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
26a80 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
26a90 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
26aa0 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
26ab0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
26ac0 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
26ad0 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
26ae0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
26af0 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74  r.** occurs.  Ot
26b00 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
26b10 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
26b20 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
26b30 74 61 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a  tabase, table.**
26b40 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74   and column that
26b50 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
26b60 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
26b70 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41  ed from..**.** A
26b80 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
26b90 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
26ba0 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20 77 69  ose postfixed wi
26bb0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
26bc0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
26bd0 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74   strings, the ot
26be0 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
26bf0 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44  turn UTF-8. {END
26c00 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50  }.**.** These AP
26c10 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
26c20 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
26c30 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
26c40 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
26c50 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
26c60 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
26c70 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
26c80 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  bol defined..**.
26c90 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49  ** {A13751}.** I
26ca0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
26cb0 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
26cc0 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
26cd0 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
26ce0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
26cf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
26d00 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
26d10 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
26d20 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
26d30 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
26d40 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
26d50 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 31 7d 20  .**.** {H13741} 
26d60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
26d70 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
26d80 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
26d90 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
26da0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
26db0 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
26dc0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
26dd0 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
26de0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20   which the.**   
26df0 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c         Nth resul
26e00 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
26e10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26e20 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63  ent] S is extrac
26e30 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted,.**         
26e40 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
26e50 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
26e60 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
26e70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  ression.**      
26e80 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65      or if unable
26e90 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
26ea0 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65  ory to store the
26eb0 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   name..**.** {H1
26ec0 33 37 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  3742} The [sqlit
26ed0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
26ee0 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  se_name16(S,N)] 
26ef0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
26f00 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
26f10 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
26f20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
26f30 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  r zero-terminate
26f40 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  d name of the da
26f50 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20  tabase.**       
26f60 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68     from which th
26f70 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
26f80 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70  umn of the [prep
26f90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26fa0 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  S is.**         
26fb0 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
26fc0 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
26fd0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20  olumn of S is a 
26fe0 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
26ff0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
27000 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
27010 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
27020 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
27030 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 33 7d  ..**.** {H13743}
27040 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
27050 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
27060 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
27070 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
27080 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55  *          the U
27090 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
270a0 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
270b0 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68 69 63   table from whic
270c0 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  h the.**        
270d0 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
270e0 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70  umn of the [prep
270f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27100 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a  S is extracted,.
27110 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e  **          or N
27120 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
27130 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20  olumn of S is a 
27140 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
27150 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
27160 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
27170 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
27180 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
27190 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 34 7d  ..**.** {H13744}
271a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
271b0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
271c0 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
271d0 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
271e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
271f0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
27200 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74  yte order zero-t
27210 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
27220 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20  f the table.**  
27230 20 20 20 20 20 20 20 20 66 72 6f 6d 20 77 68 69          from whi
27240 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ch the Nth resul
27250 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
27260 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27270 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20  ent] S is.**    
27280 20 20 20 20 20 20 65 78 74 72 61 63 74 65 64 2c        extracted,
27290 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
272a0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
272b0 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
272c0 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  ression.**      
272d0 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65      or if unable
272e0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
272f0 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65  ory to store the
27300 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   name..**.** {H1
27310 33 37 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  3745} The [sqlit
27320 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
27330 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _name(S,N)] inte
27340 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
27350 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
27360 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d   the UTF-8 zero-
27370 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
27380 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
27390 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74  umn from which t
273a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
273b0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
273c0 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
273d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
273e0 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20  s extracted,.** 
273f0 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
27400 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
27410 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
27420 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
27430 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
27440 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
27450 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
27460 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
27470 2a 0a 2a 2a 20 7b 48 31 33 37 34 36 7d 20 54 68  *.** {H13746} Th
27480 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
27490 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
274a0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
274b0 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
274c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55  *          the U
274d0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
274e0 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72  e order zero-ter
274f0 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
27500 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20  the table.**    
27510 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 66 72 6f        column fro
27520 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20  m which the Nth 
27530 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
27540 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27550 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27560 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61  ment] S is extra
27570 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66  cted, or NULL if
27580 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a   the Nth column.
27590 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 53  **          of S
275a0 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78   is a general ex
275b0 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66 20 75  pression or if u
275c0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
275d0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20  e memory.**     
275e0 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20 74 68       to store th
275f0 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e name..**.** {H
27600 31 33 37 34 38 7d 20 54 68 65 20 72 65 74 75 72  13748} The retur
27610 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a  n values from.**
27620 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
27630 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
27640 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
27650 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
27660 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  aces].**        
27670 20 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20    are valid for 
27680 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20  the lifetime of 
27690 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
276a0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20  atement].**     
276b0 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 74 68       or until th
276c0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 63 68  e encoding is ch
276d0 61 6e 67 65 64 20 62 79 20 61 6e 6f 74 68 65 72  anged by another
276e0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20   metadata.**    
276f0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
27700 63 61 6c 6c 20 66 6f 72 20 74 68 65 20 73 61 6d  call for the sam
27710 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
27720 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ment and column.
27730 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
27740 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35  NS:.**.** {A1375
27750 31 7d 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  1} If two or mor
27760 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
27770 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20  ne or more.**   
27780 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
27790 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
277a0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
277b0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
277c0 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  s].**          f
277d0 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
277e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
277f0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
27800 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  mn.**          a
27810 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
27820 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
27830 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
27840 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
27850 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
27860 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
27870 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
27880 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
27890 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
278a0 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
278b0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
278c0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
278d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
278e0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
278f0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
27900 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
27910 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
27920 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
27930 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
27940 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
27950 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
27960 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
27970 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
27980 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
27990 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
279a0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
279b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
279c0 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
279d0 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
279e0 74 20 7b 48 31 33 37 36 30 7d 20 3c 53 31 30 37  t {H13760} <S107
279f0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  00>.**.** The fi
27a00 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
27a10 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
27a20 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
27a30 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
27a40 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
27a50 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
27a60 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
27a70 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
27a80 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
27a90 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
27aa0 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
27ab0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
27ac0 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
27ad0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
27ae0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
27af0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
27b00 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68 65 20  turned.  If the 
27b10 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
27b20 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
27b30 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
27b40 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
27b50 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
27b60 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
27b70 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73  * The returned s
27b80 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
27b90 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b  UTF-8 encoded. {
27ba0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  END}.**.** For e
27bb0 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
27bc0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
27bd0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
27be0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
27bf0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
27c00 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
27c10 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
27c20 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
27c30 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
27c40 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
27c50 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
27c60 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
27c70 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
27c80 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
27c90 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
27ca0 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
27cb0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
27cc0 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
27cd0 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a  lumn (i==0)..**.
27ce0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  ** SQLite uses d
27cf0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
27d00 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74  typing.  So just
27d10 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
27d20 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
27d30 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
27d40 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
27d50 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
27d60 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
27d70 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
27d80 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
27d90 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
27da0 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
27db0 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
27dc0 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
27dd0 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
27de0 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f   Type.** is asso
27df0 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
27e00 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
27e10 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
27e20 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
27e30 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
27e40 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ues..**.** INVAR
27e50 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
27e60 33 37 36 31 7d 20 20 41 20 73 75 63 63 65 73 73  3761}  A success
27e70 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
27e80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
27e90 74 79 70 65 28 53 2c 4e 29 5d 20 72 65 74 75 72  type(S,N)] retur
27ea0 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
27eb0 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
27ec0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63  d UTF-8 string c
27ed0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65  ontaining the de
27ee0 63 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 0a  clared datatype.
27ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 20  **           of 
27f00 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
27f10 20 74 68 61 74 20 61 70 70 65 61 72 73 20 61 73   that appears as
27f20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
27f30 28 6e 75 6d 62 65 72 65 64 0a 2a 2a 20 20 20 20  (numbered.**    
27f40 20 20 20 20 20 20 20 66 72 6f 6d 20 30 29 20 6f         from 0) o
27f50 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
27f60 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
27f70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
27f80 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 32 7d 20 20  **.** {H13762}  
27f90 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
27fa0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
27fb0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
27fc0 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
27fd0 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a 65 72     returns a zer
27fe0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
27ff0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
28000 6f 72 64 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20  order string.** 
28010 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 61 69            contai
28020 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65  ning the declare
28030 64 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68  d datatype of th
28040 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
28050 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a 20 20  hat appears.**  
28060 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20           as the 
28070 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62  Nth column (numb
28080 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f 66 20  ered from 0) of 
28090 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74  the result set t
280a0 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
280b0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
280c0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a  tement] S..**.**
280d0 20 7b 48 31 33 37 36 33 7d 20 20 49 66 20 4e 20   {H13763}  If N 
280e0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 30 20 6f  is less than 0 o
280f0 72 20 4e 20 69 73 20 67 72 65 61 74 65 72 20 74  r N is greater t
28100 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a  han or equal to.
28110 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
28120 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
28130 6e 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  ns in the [prepa
28140 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
28150 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  ,.**           o
28160 72 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  r if the Nth col
28170 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e 20 65  umn of S is an e
28180 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
28190 71 75 65 72 79 20 72 61 74 68 65 72 0a 2a 2a 20  query rather.** 
281a0 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 61            than a
281b0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f   table column, o
281c0 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
281d0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
281e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63  .**           oc
281f0 63 75 72 73 20 64 75 72 69 6e 67 20 65 6e 63 6f  curs during enco
28200 64 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73  ding conversions
28210 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
28220 20 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71      calls to [sq
28230 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
28240 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a  ltype(S,N)] or.*
28250 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
28260 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
28270 74 79 70 65 31 36 28 53 2c 4e 29 5d 20 72 65 74  type16(S,N)] ret
28280 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e  urn NULL..*/.con
28290 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
282a0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
282b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
282c0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
282d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
282e0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
282f0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
28300 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28310 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
28320 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 32 30  Statement {H1320
28330 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S10000>.**.*
28340 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
28350 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
28360 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
28370 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
28380 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28390 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
283a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
283b0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
283c0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
283d0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
283e0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
283f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28400 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
28410 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
28420 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
28430 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
28440 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
28450 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
28460 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
28470 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
28480 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
28490 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
284a0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
284b0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
284c0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
284d0 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
284e0 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
284f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
28500 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28510 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
28520 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
28530 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
28540 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
28550 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
28560 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
28570 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
28580 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
28590 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
285a0 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
285b0 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
285c0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
285d0 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
285e0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
285f0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61  *.** In the lega
28600 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
28610 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
28620 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
28630 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
28640 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
28650 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
28660 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
28670 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
28680 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22 76 32  .** With the "v2
28690 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
286a0 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
286b0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
286c0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
286d0 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
286e0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
286f0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  well..**.** [SQL
28700 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
28710 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
28720 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
28730 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
28740 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
28750 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
28760 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66   do its job.  If
28770 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
28780 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
28790 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
287a0 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
287b0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
287c0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
287d0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
287e0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
287f0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
28800 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
28810 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78  s within a.** ex
28820 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
28830 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
28840 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
28850 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
28860 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
28870 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
28880 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
28890 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
288a0 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
288b0 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
288c0 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
288d0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
288e0 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
288f0 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
28900 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
28910 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
28920 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
28930 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
28940 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
28950 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
28960 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
28970 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
28980 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
28990 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
289a0 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
289b0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
289c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
289d0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
289e0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
289f0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
28a00 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
28a10 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
28a20 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
28a30 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
28a40 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
28a50 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
28a60 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
28a70 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
28a80 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
28a90 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51   data..**.** [SQ
28aa0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
28ab0 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
28ac0 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
28ad0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
28ae0 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
28af0 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
28b00 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
28b10 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
28b20 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
28b30 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
28b40 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
28b50 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
28b60 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
28b70 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65 67 61  ** With the lega
28b80 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
28b90 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
28ba0 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
28bb0 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
28bc0 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
28bd0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
28be0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
28bf0 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
28c00 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
28c10 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
28c20 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
28c30 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
28c40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
28c50 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
28c60 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
28c70 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
28c80 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
28c90 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
28ca0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
28cb0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
28cc0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
28cd0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
28ce0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
28cf0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
28d00 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
28d10 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
28d20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
28d30 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
28d40 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
28d50 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
28d60 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
28d70 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
28d80 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
28d90 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
28da0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
28db0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
28dc0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
28dd0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
28de0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28df0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
28e00 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
28e10 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
28e20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
28e30 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ime..**.** <b>Go
28e40 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
28e50 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
28e60 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
28e70 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
28e80 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
28e90 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
28ea0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
28eb0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
28ec0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
28ed0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
28ee0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
28ef0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
28f00 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
28f10 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
28f20 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
28f30 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
28f40 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
28f50 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
28f60 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
28f70 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
28f80 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
28f90 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
28fa0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
28fb0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
28fc0 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
28fd0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
28fe0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
28ff0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
29000 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
29010 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
29020 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
29030 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
29040 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
29050 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
29060 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
29070 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
29080 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29090 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
290a0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
290b0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
290c0 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
290d0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
290e0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
290f0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
29100 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
29110 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
29120 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
29130 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
29140 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
29150 2a 2a 0a 2a 2a 20 7b 48 31 33 32 30 32 7d 20 20  **.** {H13202}  
29160 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  If the [prepared
29170 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
29180 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 75 6e   ready to be run
29190 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
291a0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65      [sqlite3_ste
291b0 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73 20 74  p(S)] advances t
291c0 68 61 74 20 70 72 65 70 61 72 65 64 20 73 74 61  hat prepared sta
291d0 74 65 6d 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20  tement until.** 
291e0 20 20 20 20 20 20 20 20 20 20 63 6f 6d 70 6c 65            comple
291f0 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74  tion or until it
29200 20 69 73 20 72 65 61 64 79 20 74 6f 20 72 65 74   is ready to ret
29210 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  urn another row 
29220 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
29230 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 2c 20      result set, 
29240 6f 72 20 75 6e 74 69 6c 20 61 6e 20 5b 73 71 6c  or until an [sql
29250 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
29260 20 69 6e 74 65 72 72 75 70 74 5d 0a 2a 2a 20 20   interrupt].**  
29270 20 20 20 20 20 20 20 20 20 6f 72 20 61 20 72 75           or a ru
29280 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f 63 63  n-time error occ
29290 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33  urs..**.** {H153
292a0 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c  04}  When a call
292b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
292c0 70 28 53 29 5d 20 63 61 75 73 65 73 20 74 68 65  p(S)] causes the
292d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
292e0 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
292f0 20 20 20 53 20 74 6f 20 72 75 6e 20 74 6f 20 63     S to run to c
29300 6f 6d 70 6c 65 74 69 6f 6e 2c 20 74 68 65 20 66  ompletion, the f
29310 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
29320 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a  [SQLITE_DONE]..*
29330 2a 0a 2a 2a 20 7b 48 31 35 33 30 36 7d 20 20 57  *.** {H15306}  W
29340 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  hen a call to [s
29350 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
29360 73 74 6f 70 73 20 62 65 63 61 75 73 65 20 69 74  stops because it
29370 20 69 73 20 72 65 61 64 79 20 74 6f 0a 2a 2a 20   is ready to.** 
29380 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
29390 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20   another row of 
293a0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2c 20  the result set, 
293b0 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
293c0 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  TE_ROW]..**.** {
293d0 48 31 35 33 30 38 7d 20 20 49 66 20 61 20 63 61  H15308}  If a ca
293e0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
293f0 74 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65  tep(S)] encounte
29400 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  rs an.**        
29410 20 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65     [sqlite3_inte
29420 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70  rrupt | interrup
29430 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65  t] or a run-time
29440 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20   error,.**      
29450 20 20 20 20 20 69 74 20 72 65 74 75 72 6e 73 20       it returns 
29460 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
29470 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74 20 69  rror code that i
29480 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20  s not one of.** 
29490 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
294a0 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  E_OK], [SQLITE_R
294b0 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OW], or [SQLITE_
294c0 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  DONE]..**.** {H1
294d0 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b 73 71  5310}  If an [sq
294e0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20  lite3_interrupt 
294f0 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20  | interrupt] or 
29500 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
29510 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 63  .**           oc
29520 63 75 72 73 20 64 75 72 69 6e 67 20 61 20 63 61  curs during a ca
29530 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
29540 74 65 70 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20  tep(S)].**      
29550 20 20 20 20 20 66 6f 72 20 61 20 5b 70 72 65 70       for a [prep
29560 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29570 53 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  S created using.
29580 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6c 65 67  **           leg
29590 61 63 79 20 69 6e 74 65 72 66 61 63 65 73 20 5b  acy interfaces [
295a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
295b0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
295c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
295d0 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 74  are16()], then t
295e0 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
295f0 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
29600 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
29610 45 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERROR], [SQLITE_
29620 42 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BUSY], or [SQLIT
29630 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e  E_MISUSE]..*/.in
29640 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
29650 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
29660 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29670 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
29680 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
29690 74 20 7b 48 31 33 37 37 30 7d 20 3c 53 31 30 37  t {H13770} <S107
296a0 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  00>.**.** Return
296b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
296c0 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 63 75  values in the cu
296d0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
296e0 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a   result set..**.
296f0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
29700 2a 0a 2a 2a 20 7b 48 31 33 37 37 31 7d 20 20 41  *.** {H13771}  A
29710 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b  fter a call to [
29720 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
29730 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 5b 53   that returns [S
29740 51 4c 49 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20  QLITE_ROW],.**  
29750 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
29760 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
29770 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c  (S)] routine wil
29780 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  l return the sam
29790 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20  e value.**      
297a0 20 20 20 20 20 61 73 20 74 68 65 20 5b 73 71 6c       as the [sql
297b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
297c0 74 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a  t(S)] function..
297d0 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 32 7d 20 20  **.** {H13772}  
297e0 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  After [sqlite3_s
297f0 74 65 70 28 53 29 5d 20 68 61 73 20 72 65 74 75  tep(S)] has retu
29800 72 6e 65 64 20 61 6e 79 20 76 61 6c 75 65 20 6f  rned any value o
29810 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
29820 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 52         [SQLITE_R
29830 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65 20 5b 73  OW] or before [s
29840 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
29850 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
29860 6f 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  on the.**       
29870 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
29880 61 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65  atement] for the
29890 20 66 69 72 73 74 20 74 69 6d 65 20 73 69 6e 63   first time sinc
298a0 65 20 69 74 20 77 61 73 0a 2a 2a 20 20 20 20 20  e it was.**     
298b0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
298c0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
298d0 64 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  d] or [sqlite3_r
298e0 65 73 65 74 20 7c 20 72 65 73 65 74 5d 2c 0a 2a  eset | reset],.*
298f0 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20  *           the 
29900 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
29910 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 20  unt(S)] routine 
29920 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f  returns zero..*/
29930 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
29940 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
29950 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
29960 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
29970 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
29980 79 70 65 73 20 7b 48 31 30 32 36 35 7d 20 3c 53  ypes {H10265} <S
29990 31 30 31 31 30 3e 3c 53 31 30 31 32 30 3e 0a 2a  10110><S10120>.*
299a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
299b0 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48  TE_TEXT.**.** {H
299c0 31 30 32 36 36 7d 20 45 76 65 72 79 20 76 61 6c  10266} Every val
299d0 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
299e0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
299f0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
29a00 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
29a10 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
29a20 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
29a30 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
29a40 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
29a50 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
29a60 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
29a70 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
29a80 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a  ** </ul> {END}.*
29a90 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
29aa0 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
29ab0 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
29ac0 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
29ad0 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
29ae0 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
29af0 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
29b00 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
29b10 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
29b20 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
29b30 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
29b40 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
29b50 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
29b60 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
29b70 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
29b80 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
29b90 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
29ba0 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
29bb0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
29bc0 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
29bd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
29be0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
29bf0 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
29c00 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
29c10 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
29c20 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
29c30 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
29c40 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
29c50 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
29c60 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
29c70 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
29c80 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
29c90 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
29ca0 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
29cb0 72 79 20 7b 48 31 33 38 30 30 7d 20 3c 53 31 30  ry {H13800} <S10
29cc0 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  700>.** KEYWORDS
29cd0 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
29ce0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
29cf0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
29d00 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c   form the "resul
29d10 74 20 73 65 74 20 71 75 65 72 79 22 20 69 6e 74  t set query" int
29d20 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erface..**.** Th
29d30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
29d40 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
29d50 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
29d60 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
29d70 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
29d80 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
29d90 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
29da0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
29db0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
29dc0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
29dd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
29de0 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
29df0 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
29e00 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
29e10 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
29e20 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
29e30 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
29e40 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
29e50 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
29e60 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
29e70 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
29e80 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
29e90 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
29ea0 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
29eb0 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66 74 6d  rned.  The leftm
29ec0 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
29ed0 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
29ee0 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
29ef0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
29f00 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
29f10 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
29f20 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
29f30 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
29f40 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
29f50 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
29f60 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
29f70 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
29f80 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
29f90 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
29fa0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
29fb0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
29fc0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
29fd0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
29fe0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
29ff0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2a000 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2a010 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2a020 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2a030 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2a040 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2a050 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2a060 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2a070 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2a080 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2a090 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2a0a0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2a0b0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2a0c0 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2a0d0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2a0e0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2a0f0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2a100 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2a110 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2a120 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2a130 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2a140 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2a150 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2a160 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2a170 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2a180 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2a190 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2a1a0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2a1b0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
2a1c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a1d0 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
2a1e0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
2a1f0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
2a200 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
2a210 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
2a220 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
2a230 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
2a240 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  .  The returned 
2a250 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
2a260 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2a270 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
2a280 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
2a290 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
2a2a0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
2a2b0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
2a2c0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2a2d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2a2e0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
2a2f0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
2a300 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
2a310 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
2a320 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
2a330 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
2a340 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
2a350 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
2a360 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2a370 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2a380 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
2a390 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
2a3a0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
2a3b0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
2a3c0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
2a3d0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
2a3e0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
2a3f0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
2a400 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2a410 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
2a420 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2a430 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a440 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
2a450 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2a460 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2a470 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2a480 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65  tring..** If the
2a490 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2a4a0 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
2a4b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a4c0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
2a4d0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2a4e0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
2a4f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2a500 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2a510 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
2a520 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2a530 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2a540 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
2a550 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2a560 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2a570 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2a580 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
2a590 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2a5a0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2a5b0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2a5c0 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c  ring..** The val
2a5d0 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  ue returned does
2a5e0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
2a5f0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2a600 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
2a610 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 46  f the string.  F
2a620 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
2a630 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
2a640 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
2a650 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
2a660 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
2a670 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2a680 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69  ters..**.** Stri
2a690 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
2a6a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a6b0 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
2a6c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2a6d0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
2a6e0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
2a6f0 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ways zero termin
2a700 61 74 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  ated.  The retur
2a710 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
2a720 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a730 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
2a740 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
2a750 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  an arbitrary.** 
2a760 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c  pointer, possibl
2a770 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  y even a NULL po
2a780 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
2a790 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a7a0 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
2a7b0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
2a7c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a7d0 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
2a7e0 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
2a7f0 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  in UTF-16 in nat
2a800 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
2a810 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e  nstead of UTF-8.
2a820 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74 65 72  .** The zero ter
2a830 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69  minator is not i
2a840 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20  ncluded in this 
2a850 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  count..**.** The
2a860 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2a870 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
2a880 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2a890 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
2a8a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2a8b0 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
2a8c0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2a8d0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
2a8e0 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
2a8f0 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
2a900 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
2a910 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
2a920 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
2a930 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
2a940 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2a950 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
2a960 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2a970 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2a980 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
2a990 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
2a9a0 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
2a9b0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
2a9c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
2a9d0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
2a9e0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2a9f0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2aa00 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
2aa10 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2aa20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2aa30 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2aa40 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
2aa50 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
2aa60 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
2aa70 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
2aa80 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
2aa90 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
2aaa0 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
2aab0 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
2aac0 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
2aad0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2aae0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
2aaf0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
2ab00 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
2ab10 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
2ab20 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  y.  The followin
2ab30 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
2ab40 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
2ab50 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
2ab60 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
2ab70 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
2ab80 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
2ab90 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
2aba0 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
2abb0 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
2abc0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
2abd0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
2abe0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2abf0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
2ac00 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
2ac10 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2ac20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2ac30 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
2ac40 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
2ac50 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
2ac60 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
2ac70 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
2ac80 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
2ac90 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
2aca0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
2acb0 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  t is NULL pointe
2acc0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2acd0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
2ace0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
2acf0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
2ad00 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
2ad10 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2ad20 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2ad30 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2ad40 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
2ad50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2ad60 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
2ad70 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
2ad80 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
2ad90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2ada0 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
2adb0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
2adc0 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69   from float to i
2add0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
2ade0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2adf0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2ae00 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
2ae10 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
2ae20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2ae30 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2ae40 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c   <td> Same as FL
2ae50 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  OAT->TEXT.** <tr
2ae60 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2ae70 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2ae80 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a  d> Use atoi().**
2ae90 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2aea0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2aeb0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28    <td> Use atof(
2aec0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
2aed0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
2aee0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
2aef0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
2af00 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
2af10 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2af20 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
2af30 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a  en use atoi().**
2af40 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2af50 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
2af60 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
2af70 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
2af80 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2af90 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2afa0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2afb0 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69  Add a zero termi
2afc0 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a  nator if needed.
2afd0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
2afe0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
2aff0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f  ** The table abo
2b000 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e  ve makes referen
2b010 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43  ce to standard C
2b020 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f   library functio
2b030 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64  ns atoi().** and
2b040 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65   atof().  SQLite
2b050 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79   does not really
2b060 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74   use these funct
2b070 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74  ions.  It has it
2b080 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c  s.** own equival
2b090 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75  ent internal rou
2b0a0 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69  tines.  The atoi
2b0b0 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61  () and atof() na
2b0c0 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  mes are.** used 
2b0d0 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72  in the table for
2b0e0 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63   brevity and bec
2b0f0 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61  ause they are fa
2b100 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a  miliar to most.*
2b110 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e  * C programmers.
2b120 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2b130 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
2b140 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
2b150 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
2b160 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
2b170 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2b180 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
2b190 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2b1a0 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
2b1b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2b1c0 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
2b1d0 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
2b1e0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
2b1f0 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
2b200 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
2b210 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
2b220 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
2b230 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2b240 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2b250 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
2b260 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2b270 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
2b280 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2b290 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
2b2a0 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
2b2b0 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
2b2c0 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
2b2d0 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
2b2e0 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
2b2f0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
2b300 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
2b310 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
2b320 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2b330 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
2b340 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b350 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
2b360 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2b370 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2b380 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2b390 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
2b3a0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2b3b0 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
2b3c0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2b3d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2b3e0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
2b3f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2b400 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2b410 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
2b420 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
2b430 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
2b440 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2b450 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
2b460 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
2b470 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
2b480 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
2b490 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
2b4a0 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
2b4b0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
2b4c0 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
2b4d0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2b4e0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
2b4f0 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
2b500 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c  r points to will
2b510 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
2b520 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
2b530 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
2b540 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
2b550 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
2b560 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
2b570 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
2b580 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
2b590 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
2b5a0 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
2b5b0 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
2b5c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
2b5d0 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
2b5e0 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
2b5f0 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
2b600 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2b610 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
2b620 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
2b630 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
2b640 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2b650 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
2b660 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2b670 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2b680 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2b690 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2b6a0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2b6b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b6c0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
2b6d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2b6e0 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
2b6f0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2b700 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
2b710 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
2b720 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2b730 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
2b740 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b750 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
2b760 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2b770 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
2b780 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
2b790 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
2b7a0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
2b7b0 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
2b7c0 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
2b7d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2b7e0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
2b7f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b800 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
2b810 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
2b820 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
2b830 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
2b840 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2b850 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2b860 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
2b870 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
2b880 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b890 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
2b8a0 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
2b8b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b8c0 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
2b8d0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2b8e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
2b8f0 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
2b900 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
2b910 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
2b920 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
2b930 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
2b940 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
2b950 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
2b960 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2b970 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2b980 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2b990 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
2b9a0 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61    The memory spa
2b9b0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
2b9c0 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
2b9d0 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
2b9e0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
2b9f0 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
2ba00 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
2ba10 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74  turned.** [sqlit
2ba20 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2ba30 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
2ba40 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
2ba50 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
2ba60 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
2ba70 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   If a memory all
2ba80 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
2ba90 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
2baa0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
2bab0 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
2bac0 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
2bad0 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
2bae0 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
2baf0 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
2bb00 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
2bb10 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
2bb20 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
2bb30 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
2bb40 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
2bb50 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
2bb60 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
2bb70 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
2bb80 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
2bb90 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2bba0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 33  S:.**.** {H13803
2bbb0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2bbc0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d  olumn_blob(S,N)]
2bbd0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2bbe0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2bbf0 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
2bc00 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
2bc10 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2bc20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  set for.**      
2bc30 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65      the [prepare
2bc40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2bc50 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20 74  nto a BLOB and t
2bc60 68 65 6e 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a  hen returns a.**
2bc70 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65            pointe
2bc80 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72 74  r to the convert
2bc90 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ed value..**.** 
2bca0 7b 48 31 33 38 30 36 7d 20 54 68 65 20 5b 73 71  {H13806} The [sq
2bcb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2bcc0 65 73 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  es(S,N)] interfa
2bcd0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ce returns the.*
2bce0 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
2bcf0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2bd00 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
2bd10 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74   (exclusive of t
2bd20 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  he.**          z
2bd30 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f  ero terminator o
2bd40 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68  n the string) th
2bd50 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
2bd60 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
2bd70 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63     most recent c
2bd80 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2bd90 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29  column_blob(S,N)
2bda0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
2bdb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2bdc0 5f 74 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a  _text(S,N)]..**.
2bdd0 2a 2a 20 7b 48 31 33 38 30 39 7d 20 54 68 65 20  ** {H13809} The 
2bde0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2bdf0 62 79 74 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e  bytes16(S,N)] in
2be00 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2be10 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2be20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2be30 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28 65  in the string (e
2be40 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a  xclusive of the.
2be50 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
2be60 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74   terminator on t
2be70 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20  he string) that 
2be80 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  was returned by 
2be90 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2bea0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2beb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
2bec0 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d  umn_text16(S,N)]
2bed0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 32 7d  ..**.** {H13812}
2bee0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2bef0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29  lumn_double(S,N)
2bf00 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2bf10 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2bf20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
2bf30 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
2bf40 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2bf50 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20   set for the.** 
2bf60 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2bf70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2bf80 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20  into a floating 
2bf90 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a  point value and.
2bfa0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2bfb0 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
2bfc0 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  at value..**.** 
2bfd0 7b 48 31 33 38 31 35 7d 20 54 68 65 20 5b 73 71  {H13815} The [sq
2bfe0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2bff0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
2c000 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2c010 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
2c020 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
2c030 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2c040 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68  esult set for th
2c050 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2c060 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c070 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62  t] S into a 64-b
2c080 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2c090 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
2c0a0 20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f    returns the lo
2c0b0 77 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 74  wer 32 bits of t
2c0c0 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  hat integer..**.
2c0d0 2a 2a 20 7b 48 31 33 38 31 38 7d 20 54 68 65 20  ** {H13818} The 
2c0e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c0f0 69 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65  int64(S,N)] inte
2c100 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2c110 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
2c120 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
2c130 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
2c140 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
2c150 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2c160 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2c170 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
2c180 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2c190 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
2c1a0 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
2c1b0 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e   copy of that in
2c1c0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  teger..**.** {H1
2c1d0 33 38 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3821} The [sqlit
2c1e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53  e3_column_text(S
2c1f0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
2c200 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2c210 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
2c220 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
2c230 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
2c240 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
2c250 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
2c260 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c270 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   S into a zero-t
2c280 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
2c290 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
2c2a0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
2c2b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2c2c0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
2c2d0 48 31 33 38 32 34 7d 20 54 68 65 20 5b 73 71 6c  H13824} The [sql
2c2e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c2f0 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
2c300 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2c310 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
2c320 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
2c330 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2c340 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20   result set for 
2c350 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c360 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c370 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65  ent] S into a ze
2c380 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d  ro-terminated 2-
2c390 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  byte.**         
2c3a0 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20   aligned UTF-16 
2c3b0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2c3c0 72 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  r string and ret
2c3d0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
2c3e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2c3f0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
2c400 20 7b 48 31 33 38 32 37 7d 20 54 68 65 20 5b 73   {H13827} The [s
2c410 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2c420 70 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  pe(S,N)] interfa
2c430 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
2c440 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53         one of [S
2c450 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51  QLITE_NULL], [SQ
2c460 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b  LITE_INTEGER], [
2c470 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a  SQLITE_FLOAT],.*
2c480 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
2c490 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51  TE_TEXT], or [SQ
2c4a0 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70  LITE_BLOB] as ap
2c4b0 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a  propriate for.**
2c4c0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 4e 74            the Nt
2c4d0 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2c4e0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2c4f0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
2c500 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
2c510 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2c520 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20  ement] S..**.** 
2c530 7b 48 31 33 38 33 30 7d 20 54 68 65 20 5b 73 71  {H13830} The [sq
2c540 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2c550 75 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ue(S,N)] interfa
2c560 63 65 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20  ce returns a.** 
2c570 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72           pointer
2c580 20 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63   to an [unprotec
2c590 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c5a0 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20 74 68  e] object for th
2c5b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
2c5c0 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2c5d0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2c5e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
2c5f0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
2c600 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2c610 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e  ement] S..*/.con
2c620 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2c630 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
2c640 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2c650 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2c660 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2c670 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c680 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2c690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c6a0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
2c6b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
2c6c0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
2c6d0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
2c6e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2c6f0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2c700 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
2c710 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2c720 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
2c730 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
2c740 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
2c750 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2c760 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
2c770 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2c780 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
2c790 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2c7a0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
2c7b0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2c7c0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
2c7d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2c7e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2c7f0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
2c800 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2c810 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
2c820 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
2c830 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
2c840 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2c850 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c860 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
2c870 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2c880 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30 30 7d   Object {H13300}
2c890 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31 30 30   <S70300><S30100
2c8a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2c8b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
2c8c0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
2c8d0 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
2c8e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c8f0 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 74  t]..** If the st
2c900 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63  atement was exec
2c910 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  uted successfull
2c920 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65  y or not execute
2c930 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a  d at all, then.*
2c940 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  * SQLITE_OK is r
2c950 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78 65 63  eturned. If exec
2c960 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ution of the sta
2c970 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68  tement failed th
2c980 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  en an.** [error 
2c990 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
2c9a0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
2c9b0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2c9c0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
2c9d0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
2c9e0 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
2c9f0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
2ca00 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
2ca10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2ca20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d  If the virtual m
2ca30 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a  achine has not.*
2ca40 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
2ca50 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20  ution when this 
2ca60 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
2ca70 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a  d, that is like.
2ca80 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  ** encountering 
2ca90 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b  an error or an [
2caa0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
2cab0 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a  t | interrupt]..
2cac0 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70  ** Incomplete up
2cad0 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c  dates may be rol
2cae0 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61  led back and tra
2caf0 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c  nsactions cancel
2cb00 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67  ed,.** depending
2cb10 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74   on the circumst
2cb20 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a  ances, and the.*
2cb30 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72  * [error code] r
2cb40 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20  eturned will be 
2cb50 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
2cb60 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2cb70 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 32 7d  :.**.** {H11302}
2cb80 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   The [sqlite3_fi
2cb90 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74 65 72  nalize(S)] inter
2cba0 66 61 63 65 20 64 65 73 74 72 6f 79 73 20 74 68  face destroys th
2cbb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2cbc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cbd0 74 5d 20 53 20 61 6e 64 20 72 65 6c 65 61 73 65  t] S and release
2cbe0 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  s all.**        
2cbf0 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c    memory and fil
2cc00 65 20 72 65 73 6f 75 72 63 65 73 20 68 65 6c 64  e resources held
2cc10 20 62 79 20 74 68 61 74 20 6f 62 6a 65 63 74 2e   by that object.
2cc20 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 34 7d 20  .**.** {H11304} 
2cc30 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2cc40 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2cc50 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2cc60 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2cc70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cc80 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
2cc90 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20   an error,.**   
2cca0 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c         then [sql
2ccb0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2ccc0 5d 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 73  ] returns that s
2ccd0 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e  ame error..*/.in
2cce0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
2ccf0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
2cd00 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2cd10 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2cd20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2cd30 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33  ment Object {H13
2cd40 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  330} <S70300>.**
2cd50 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2cd60 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
2cd70 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
2cd80 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
2cd90 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2cda0 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
2cdb0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
2cdc0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
2cdd0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  xecuted..** Any 
2cde0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
2cdf0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
2ce00 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
2ce10 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
2ce20 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2ce30 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2ce40 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
2ce50 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
2ce60 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
2ce70 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2ce80 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
2ce90 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
2cea0 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65 20 5b  * {H11332} The [
2ceb0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2cec0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
2ced0 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
2cee0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
2cef0 20 20 20 20 20 20 20 20 20 20 62 61 63 6b 20 74            back t
2cf00 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
2cf10 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
2cf20 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49  **.** {H11334} I
2cf30 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2cf40 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2cf50 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2cf60 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2cf70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cf80 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
2cf90 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
2cfa0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
2cfb0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
2cfc0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2cfd0 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
2cfe0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
2cff0 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  on S,.**        
2d000 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
2d010 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2d020 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
2d030 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20 49 66  *.** {H11336} If
2d040 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2d050 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2d060 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
2d070 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2d080 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d090 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
2d0a0 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
2d0b0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2d0c0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2d0d0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
2d0e0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2d0f0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38  ]..**.** {H11338
2d100 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2d110 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2d120 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
2d130 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
2d140 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 6e 79            of any
2d150 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2d160 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
2d170 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2d180 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
2d190 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
2d1a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2d1b0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2d1c0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
2d1d0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
2d1e0 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 31 30  Functions {H1610
2d1f0 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b  0} <S20200>.** K
2d200 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
2d210 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2d220 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
2d230 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2d240 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2d250 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
2d260 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
2d270 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2d280 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
2d290 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  se two functions
2d2a0 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
2d2b0 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
2d2c0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2d2d0 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
2d2e0 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
2d2f0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2d300 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
2d310 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
2d320 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
2d330 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2d340 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
2d350 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
2d360 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a  e between the.**
2d370 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65   two is that the
2d380 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2d390 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r, the name of t
2d3a0 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63  he (scalar) func
2d3b0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2d3c0 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64  gate, is encoded
2d3d0 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71   in UTF-8 for sq
2d3e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d3f0 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d  ction() and UTF-
2d400 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  16.** for sqlite
2d410 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2d420 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  n16()..**.** The
2d430 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2d440 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
2d450 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
2d460 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
2d470 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
2d480 20 62 65 20 61 64 64 65 64 2e 20 20 49 66 20 61   be added.  If a
2d490 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20   single program 
2d4a0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
2d4b0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
2d4c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e  onnection intern
2d4d0 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20 66  ally, then SQL f
2d4e0 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
2d4f0 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75 61   added individua
2d500 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64  lly to.** each d
2d510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d520 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  on..**.** The se
2d530 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2d540 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
2d550 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
2d560 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
2d570 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 54  ** redefined.  T
2d580 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
2d590 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
2d5a0 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65   to 255 bytes, e
2d5b0 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74  xclusive of.** t
2d5c0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
2d5d0 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  or.  Note that t
2d5e0 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c  he name length l
2d5f0 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73  imit is in bytes
2d600 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74  , not.** charact
2d610 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65 6d 70  ers.  Any attemp
2d620 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
2d630 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
2d640 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
2d650 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
2d660 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67  ITE_ERROR] being
2d670 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2d680 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
2d690 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
2d6a0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2d6b0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
2d6c0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2d6d0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
2d6e0 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70  takes. If this p
2d6f0 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
2d700 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53  tive, then the S
2d710 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2d720 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
2d730 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
2d740 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  of arguments..**
2d750 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
2d760 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
2d770 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
2d780 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
2d790 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
2d7a0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
2d7b0 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
2d7c0 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
2d7d0 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75  ers.  Any SQL fu
2d7e0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2d7f0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ation should be 
2d800 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
2d810 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c  work with UTF-8,
2d820 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
2d830 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
2d840 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2d850 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
2d860 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
2d870 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
2d880 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69  n another.  It i
2d890 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20  s allowed to.** 
2d8a0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2d8b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2d8c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
2d8d0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
2d8e0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
2d8f0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2d900 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
2d910 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
2d920 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
2d930 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  ** When multiple
2d940 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2d950 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2d960 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
2d970 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
2d980 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
2d990 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
2d9a0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
2d9b0 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
2d9c0 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
2d9d0 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
2d9e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2d9f0 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
2da00 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a  are what text.**
2da10 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
2da20 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
2da30 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
2da40 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e  ld be [SQLITE_AN
2da50 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  Y]..**.** The fi
2da60 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
2da70 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
2da80 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
2da90 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2daa0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
2dab0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
2dac0 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
2dad0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
2dae0 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a  r_data()]..**.**
2daf0 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69   The seventh, ei
2db00 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70  ghth and ninth p
2db10 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
2db20 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
2db30 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
2db40 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
2db50 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
2db60 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
2db70 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2db80 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73  * aggregate. A s
2db90 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
2dba0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2dbb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2dbc0 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
2dbd0 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c  llback only, NUL
2dbe0 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c  L pointers shoul
2dbf0 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  d be passed as t
2dc00 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
2dc10 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
2dc20 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20  s. An aggregate 
2dc30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2dc40 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2dc50 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
2dc60 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
2dc70 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62  nd NULL should b
2dc80 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
2dc90 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e  nc. To delete an
2dca0 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
2dcb0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2dcc0 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
2dcd0 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  L for all three 
2dce0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
2dcf0 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ks..**.** It is 
2dd00 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
2dd10 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
2dd20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2dd30 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
2dd40 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
2dd50 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
2dd60 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
2dd70 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
2dd80 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
2dd90 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
2dda0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2ddb0 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  gs.  SQLite will
2ddc0 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
2ddd0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20  ementation most 
2dde0 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
2ddf0 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
2de00 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
2de10 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 41  tion is used.  A
2de20 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2de30 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
2de40 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
2de50 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
2de60 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
2de70 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
2de80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2de90 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
2dea0 76 65 20 6e 41 72 67 2e 20 20 41 20 66 75 6e 63  ve nArg.  A func
2deb0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
2dec0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
2ded0 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
2dee0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
2def0 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
2df00 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
2df10 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
2df20 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2df30 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
2df40 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68  ** A function wh
2df50 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2df60 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62   difference is b
2df70 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61  etween UTF16le a
2df80 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73  nd UTF16be.** is
2df90 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20   a closer match 
2dfa0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
2dfb0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2dfc0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
2dfd0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38  .** between UTF8
2dfe0 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a   and UTF16..**.*
2dff0 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74  * Built-in funct
2e000 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
2e010 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
2e020 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e030 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20  d functions..** 
2e040 54 68 65 20 66 69 72 73 74 20 61 70 70 6c 69 63  The first applic
2e050 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2e060 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 67 69  nction with a gi
2e070 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 64  ven name overrid
2e080 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d  es all.** built-
2e090 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20  in functions in 
2e0a0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
2e0b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
2e0c0 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ith the same nam
2e0d0 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74  e..** Subsequent
2e0e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2e0f0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f  ined functions o
2e100 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  f the same name 
2e110 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 20 0a 2a  only override .*
2e120 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 63 61 74  * prior applicat
2e130 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2e140 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 61  tions that are a
2e150 6e 20 65 78 61 63 74 20 6d 61 74 63 68 20 66 6f  n exact match fo
2e160 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  r the.** number 
2e170 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e  of parameters an
2e180 64 20 70 72 65 66 65 72 72 65 64 20 65 6e 63 6f  d preferred enco
2e190 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ding..**.** An a
2e1a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2e1b0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
2e1c0 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
2e1d0 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
2e1e0 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
2e1f0 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
2e200 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
2e210 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
2e220 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
2e230 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
2e240 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
2e250 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
2e260 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
2e270 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
2e280 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2e290 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 7d 20 54  **.** {H16103} T
2e2a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2e2b0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c  te_function16(D,
2e2c0 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  X,...)] interfac
2e2d0 65 20 73 68 61 6c 6c 20 62 65 68 61 76 65 0a 2a  e shall behave.*
2e2e0 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 5b 73  *          as [s
2e2f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2e300 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d  nction(D,X,...)]
2e310 20 69 6e 20 65 76 65 72 79 20 77 61 79 20 65 78   in every way ex
2e320 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20  cept that it.** 
2e330 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 70 72           interpr
2e340 65 74 73 20 74 68 65 20 58 20 61 72 67 75 6d 65  ets the X argume
2e350 6e 74 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69  nt as zero-termi
2e360 6e 61 74 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20  nated UTF-16.** 
2e370 20 20 20 20 20 20 20 20 20 6e 61 74 69 76 65 20           native 
2e380 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65  byte order inste
2e390 61 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65  ad of as zero-te
2e3a0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a  rminated UTF-8..
2e3b0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 36 7d 20 41  **.** {H16106} A
2e3c0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
2e3d0 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  cation of the.**
2e3e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2e3f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e400 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d  on(D,X,N,E,...)]
2e410 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
2e420 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 20 20 20   register.**    
2e430 20 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63 65        or replace
2e440 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  s callback funct
2e450 69 6f 6e 73 20 69 6e 20 74 68 65 20 5b 64 61 74  ions in the [dat
2e460 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e470 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] D.**          
2e480 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
2e490 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2e4a0 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20  on named X with 
2e4b0 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  N parameters.** 
2e4c0 20 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 76           and hav
2e4d0 69 6e 67 20 61 20 70 72 65 66 65 72 72 65 64 20  ing a preferred 
2e4e0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66  text encoding of
2e4f0 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30   E..**.** {H1610
2e500 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  9} A successful 
2e510 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2e520 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2e530 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
2e540 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  )].**          s
2e550 68 61 6c 6c 20 72 65 70 6c 61 63 65 20 74 68 65  hall replace the
2e560 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20   P, F, S, and L 
2e570 76 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e 79 20  values from any 
2e580 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68  prior calls with
2e590 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2e5a0 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61   same D, X, N, a
2e5b0 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a  nd E values..**.
2e5c0 2a 2a 20 7b 48 31 36 31 31 32 7d 20 54 68 65 20  ** {H16112} The 
2e5d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e5e0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e  function(D,X,...
2e5f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
2e600 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20  ll fail.**      
2e610 20 20 20 20 69 66 20 74 68 65 20 53 51 4c 20 66      if the SQL f
2e620 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69  unction name X i
2e630 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 6f  s.**          lo
2e640 6e 67 65 72 20 74 68 61 6e 20 32 35 35 20 62 79  nger than 255 by
2e650 74 65 73 20 65 78 63 6c 75 73 69 76 65 20 6f 66  tes exclusive of
2e660 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2e670 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ator..**.** {H16
2e680 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  118} The [sqlite
2e690 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2e6a0 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
2e6b0 4c 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  L)] interface.**
2e6c0 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
2e6d0 66 61 69 6c 20 75 6e 6c 65 73 73 20 65 69 74 68  fail unless eith
2e6e0 65 72 20 46 20 69 73 20 4e 55 4c 4c 20 61 6e 64  er F is NULL and
2e6f0 20 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e   S and L are non
2e700 2d 4e 55 4c 4c 20 6f 72 0a 2a 2a 2a 20 20 20 20  -NULL or.***    
2e710 20 20 20 20 20 46 20 69 73 20 6e 6f 6e 2d 4e 55       F is non-NU
2e720 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61  LL and S and L a
2e730 72 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  re NULL..**.** {
2e740 48 31 36 31 32 31 7d 20 54 68 65 20 5b 73 71 6c  H16121} The [sql
2e750 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2e760 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74  tion(D,...)] int
2e770 65 72 66 61 63 65 20 73 68 61 6c 6c 20 66 61 69  erface shall fai
2e780 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20  ls with an.**   
2e790 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64         error cod
2e7a0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 53  e of [SQLITE_BUS
2e7b0 59 5d 20 69 66 20 74 68 65 72 65 20 65 78 69 73  Y] if there exis
2e7c0 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
2e7d0 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20  ements].**      
2e7e0 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20 77      associated w
2e7f0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2e800 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
2e810 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 34 7d 20  .**.** {H16124} 
2e820 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2e830 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2e840 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ,N,...)] interfa
2e850 63 65 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69  ce shall fail wi
2e860 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  th.**          a
2e870 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20  n error code of 
2e880 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
2e890 66 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  f parameter N is
2e8a0 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20   less.**        
2e8b0 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65    than -1 or gre
2e8c0 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a  ater than 127..*
2e8d0 2a 0a 2a 2a 20 7b 48 31 36 31 32 37 7d 20 57 68  *.** {H16127} Wh
2e8e0 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  en N is non-nega
2e8f0 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c 69 74  tive, the [sqlit
2e900 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e910 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a  on(D,X,N,...)].*
2e920 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
2e930 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73  face shall regis
2e940 74 65 72 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f  ter callbacks to
2e950 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   be invoked for 
2e960 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2e970 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  SQL function.** 
2e980 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58           named X
2e990 20 77 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72   when the number
2e9a0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   of arguments to
2e9b0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2e9c0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  n is.**         
2e9d0 20 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a   exactly N..**.*
2e9e0 2a 20 7b 48 31 36 31 33 30 7d 20 57 68 65 6e 20  * {H16130} When 
2e9f0 4e 20 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71  N is -1, the [sq
2ea00 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ea10 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29  ction(D,X,N,...)
2ea20 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
2ea30 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65  terface shall re
2ea40 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 73  gister callbacks
2ea50 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66   to be invoked f
2ea60 6f 72 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20  or the SQL.**   
2ea70 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
2ea80 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61 6e 79  named X with any
2ea90 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2eaa0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ents..**.** {H16
2eab0 31 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20  133} When calls 
2eac0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2ead0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2eae0 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  N,...)].**      
2eaf0 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74      specify mult
2eb00 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2eb10 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2eb20 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20   function X.**  
2eb30 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 6e          and when
2eb40 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   one implementat
2eb50 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64  ion has N>=0 and
2eb60 20 74 68 65 20 6f 74 68 65 72 20 68 61 73 20 4e   the other has N
2eb70 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20 20  =(-1).**        
2eb80 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    the implementa
2eb90 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
2eba0 7a 65 72 6f 20 4e 20 73 68 61 6c 6c 20 62 65 20  zero N shall be 
2ebb0 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a  preferred..**.**
2ebc0 20 7b 48 31 36 31 33 36 7d 20 57 68 65 6e 20 63   {H16136} When c
2ebd0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2ebe0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ebf0 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a  (D,X,N,E,...)].*
2ec00 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69  *          speci
2ec10 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  fy multiple impl
2ec20 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2ec30 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2ec40 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20   X with.**      
2ec50 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d      the same num
2ec60 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2ec70 20 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 66   N but with diff
2ec80 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  erent.**        
2ec90 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74    encodings E, t
2eca0 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  hen the implemen
2ecb0 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d  tation where E m
2ecc0 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20  atches the.**   
2ecd0 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20         database 
2ece0 65 6e 63 6f 64 69 6e 67 20 73 68 61 6c 6c 20 70  encoding shall p
2ecf0 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  referred..**.** 
2ed00 7b 48 31 36 31 33 39 7d 20 46 6f 72 20 61 6e 20  {H16139} For an 
2ed10 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2ed20 6e 63 74 69 6f 6e 20 63 72 65 61 74 65 64 20 75  nction created u
2ed30 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
2ed40 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ed50 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2ed60 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20  E,P,0,S,L)] the 
2ed70 66 69 6e 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20  finalizer.**    
2ed80 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c        function L
2ed90 20 73 68 61 6c 6c 20 61 6c 77 61 79 73 20 62 65   shall always be
2eda0 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79   invoked exactly
2edb0 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a 2a 20   once if the.** 
2edc0 20 20 20 20 20 20 20 20 20 73 74 65 70 20 66 75           step fu
2edd0 6e 63 74 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c  nction S is call
2ede0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
2edf0 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  imes..**.** {H16
2ee00 31 34 32 7d 20 57 68 65 6e 20 53 51 4c 69 74 65  142} When SQLite
2ee10 20 69 6e 76 6f 6b 65 73 20 65 69 74 68 65 72 20   invokes either 
2ee20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 53 74  the xFunc or xSt
2ee30 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a  ep function of.*
2ee40 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 61 70  *          an ap
2ee50 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2ee60 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  d SQL function o
2ee70 72 20 61 67 67 72 65 67 61 74 65 20 63 72 65 61  r aggregate crea
2ee80 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
2ee90 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  by [sqlite3_crea
2eea0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f  te_function()] o
2eeb0 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
2eec0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
2eed0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2eee0 6e 20 74 68 65 20 61 72 72 61 79 20 6f 66 20 5b  n the array of [
2eef0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2ef00 62 6a 65 63 74 73 20 70 61 73 73 65 64 20 61 73  bjects passed as
2ef10 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2ef20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2ef30 20 73 68 61 6c 6c 20 62 65 20 5b 70 72 6f 74 65   shall be [prote
2ef40 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ef50 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  ue] objects..*/.
2ef60 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2ef70 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
2ef80 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2ef90 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
2efa0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2efb0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2efc0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2efd0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2efe0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2eff0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2f000 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2f010 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2f020 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2f030 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2f040 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2f050 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2f060 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
2f070 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f080 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
2f090 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
2f0a0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
2f0b0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2f0c0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2f0d0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2f0e0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2f0f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2f100 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2f110 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2f120 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2f130 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2f140 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2f150 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
2f160 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
2f170 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f180 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20   Text Encodings 
2f190 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30  {H10267} <S50200
2f1a0 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a  > <H16100>.**.**
2f1b0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
2f1c0 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
2f1d0 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
2f1e0 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
2f1f0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
2f200 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
2f210 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
2f220 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
2f230 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
2f240 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
2f250 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
2f260 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
2f270 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
2f280 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
2f290 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
2f2a0 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
2f2b0 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
2f2c0 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
2f2d0 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
2f2e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f2f0 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
2f300 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2f310 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
2f320 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2f330 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
2f340 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
2f350 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
2f360 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
2f370 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
2f380 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2f390 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
2f3a0 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
2f3b0 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
2f3c0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
2f3d0 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
2f3e0 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
2f3f0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
2f400 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2f410 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
2f420 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
2f430 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
2f440 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
2f450 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
2f460 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
2f470 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
2f480 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
2f490 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
2f4a0 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
2f4b0 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e  ou want they do.
2f4c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  .*/.SQLITE_DEPRE
2f4d0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2f4e0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
2f4f0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2f500 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2f510 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2f520 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
2f530 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2f540 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2f550 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
2f560 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2f570 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
2f580 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
2f590 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2f5a0 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
2f5b0 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
2f5c0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2f5d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
2f5e0 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
2f5f0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
2f600 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2f610 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
2f620 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
2f630 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76  te3_int64,int),v
2f640 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
2f650 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
2f660 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
2f670 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
2f680 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48  ameter Values {H
2f690 31 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  15100} <S20200>.
2f6a0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
2f6b0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
2f6c0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
2f6d0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2f6e0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
2f6f0 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
2f700 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
2f710 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
2f720 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
2f730 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
2f740 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
2f750 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
2f760 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
2f770 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
2f780 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
2f790 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
2f7a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f7b0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
2f7c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f7d0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
2f7e0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
2f7f0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2f800 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
2f810 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
2f820 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
2f830 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
2f840 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
2f850 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
2f860 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
2f870 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2f880 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
2f890 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
2f8a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
2f8b0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
2f8c0 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
2f8d0 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
2f8e0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
2f8f0 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
2f900 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
2f910 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2f920 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
2f930 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
2f940 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
2f950 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2f960 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2f970 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
2f980 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
2f990 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
2f9a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2f9b0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
2f9c0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
2f9d0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
2f9e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2f9f0 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
2fa00 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
2fa10 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
2fa20 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
2fa30 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20  ** except that  
2fa40 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
2fa50 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72  ake a single [pr
2fa60 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2fa70 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
2fa80 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
2fa90 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73   of a [sqlite3_s
2faa0 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e  tmt*] pointer an
2fab0 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c  d an integer col
2fac0 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  umn number..**.*
2fad0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
2fae0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
2faf0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
2fb00 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
2fb10 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
2fb20 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
2fb30 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
2fb40 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
2fb50 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
2fb60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
2fb70 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
2fb80 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
2fb90 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
2fba0 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
2fbb0 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
2fbc0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
2fbd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2fbe0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
2fbf0 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
2fc00 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
2fc10 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
2fc20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
2fc30 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
2fc40 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
2fc50 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
2fc60 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
2fc70 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
2fc80 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
2fc90 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
2fca0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
2fcb0 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
2fcc0 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
2fcd0 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
2fce0 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
2fcf0 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
2fd00 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
2fd10 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
2fd20 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
2fd30 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
2fd40 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
2fd50 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
2fd60 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
2fd70 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2fd80 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
2fd90 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
2fda0 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  d..**.** Please 
2fdb0 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
2fdc0 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
2fdd0 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
2fde0 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
2fdf0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
2fe00 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
2fe10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2fe20 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
2fe30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2fe40 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
2fe50 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
2fe60 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
2fe70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2fe80 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
2fe90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2fea0 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
2feb0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
2fec0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
2fed0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
2fee0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2fef0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
2ff00 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
2ff10 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
2ff20 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2ff30 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
2ff40 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2ff50 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
2ff60 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2ff70 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 33 7d 20  .**.** {H15103} 
2ff80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2ff90 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65  ue_blob(V)] inte
2ffa0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2ffb0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2ffc0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ffd0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2ffe0 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e  V into a BLOB an
2fff0 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  d then.**       
30000 20 20 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69     returns a poi
30010 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76  nter to the conv
30020 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a  erted value..**.
30030 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54 68 65 20  ** {H15106} The 
30040 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
30050 79 74 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61  ytes(V)] interfa
30060 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ce returns the.*
30070 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
30080 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
30090 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
300a0 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74   (exclusive of t
300b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  he.**          z
300c0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f  ero terminator o
300d0 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68  n the string) th
300e0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
300f0 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
30100 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63     most recent c
30110 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
30120 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f  value_blob(V)] o
30130 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
30140 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30150 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  t(V)]..**.** {H1
30160 35 31 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  5109} The [sqlit
30170 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
30180 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (V)] interface r
30190 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
301a0 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
301b0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
301c0 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20  ring (exclusive 
301d0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
301e0 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74     zero terminat
301f0 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
30200 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
30210 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ned by the.**   
30220 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65         most rece
30230 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
30240 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
30250 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  (V)],.**        
30260 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65    [sqlite3_value
30270 5f 74 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f  _text16be(V)], o
30280 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
30290 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a  _text16le(V)]..*
302a0 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d 20 54 68  *.** {H15112} Th
302b0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
302c0 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65  _double(V)] inte
302d0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
302e0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
302f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30300 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
30310 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e  V into a floatin
30320 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e  g point value an
30330 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
30340 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
30350 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  that value..**.*
30360 2a 20 7b 48 31 35 31 31 35 7d 20 54 68 65 20 5b  * {H15115} The [
30370 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
30380 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(V)] interface 
30390 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
303a0 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
303b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
303c0 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
303d0 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
303e0 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20   integer and.** 
303f0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
30400 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69   the lower 32 bi
30410 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  ts of that integ
30420 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31  er..**.** {H1511
30430 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
30440 76 61 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20  value_int64(V)] 
30450 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
30460 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
30470 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
30480 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
30490 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d  ect V into a 64-
304a0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
304b0 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  er and.**       
304c0 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
304d0 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65  y of that intege
304e0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 31  r..**.** {H15121
304f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
30500 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e  alue_text(V)] in
30510 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
30520 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30530 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
30540 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30550 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  t V into a zero-
30560 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
30570 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
30580 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ing and returns 
30590 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61  a pointer to tha
305a0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
305b0 7b 48 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71  {H15124} The [sq
305c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
305d0 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  16(V)] interface
305e0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
305f0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
30600 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
30610 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
30620 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
30630 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20  ted 2-byte.**   
30640 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55         aligned U
30650 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
30660 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
30670 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
30680 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
30690 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
306a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 37 7d 20  .**.** {H15127} 
306b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
306c0 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20  ue_text16be(V)] 
306d0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
306e0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
306f0 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
30700 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
30710 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72  ect V into a zer
30720 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62  o-terminated 2-b
30730 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  yte.**          
30740 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62  aligned UTF-16 b
30750 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  ig-endian.**    
30760 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64        string and
30770 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
30780 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
30790 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 30  g..**.** {H15130
307a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
307b0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29  alue_text16le(V)
307c0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
307d0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
307e0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
307f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
30800 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a  bject V into a z
30810 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32  ero-terminated 2
30820 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  -byte.**        
30830 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36    aligned UTF-16
30840 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a   little-endian.*
30850 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
30860 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
30870 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
30880 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
30890 31 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69  15133} The [sqli
308a0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56  te3_value_type(V
308b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
308c0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
308d0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
308e0 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  NULL], [SQLITE_I
308f0 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
30900 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20  _FLOAT],.**     
30910 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58       [SQLITE_TEX
30920 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42  T], or [SQLITE_B
30930 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
30940 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  ate for.**      
30950 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
30960 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
30970 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 36 7d  ..**.** {H15136}
30980 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
30990 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
309a0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
309b0 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20  onverts.**      
309c0 20 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74      the [protect
309d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
309e0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
309f0 65 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65  either an intege
30a00 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  r or.**         
30a10 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
30a20 74 20 76 61 6c 75 65 20 69 66 20 69 74 20 63 61  t value if it ca
30a30 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20  n do so without 
30a40 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  loss of.**      
30a50 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c      information,
30a60 20 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65   and returns one
30a70 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   of [SQLITE_NULL
30a80 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
30a90 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
30aa0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
30ab0 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
30ac0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
30ad0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
30ae0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
30af0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
30b00 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
30b10 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30b20 20 56 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e   V after the con
30b30 76 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e  version attempt.
30b40 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
30b50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
30b60 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
30b70 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
30b80 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
30b90 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
30ba0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
30bb0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76  ytes16(sqlite3_v
30bc0 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73  alue*);.double s
30bd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75  qlite3_value_dou
30be0 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble(sqlite3_valu
30bf0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
30c00 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
30c10 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69  e3_value*);.sqli
30c20 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
30c30 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
30c40 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
30c50 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
30c60 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
30c70 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
30c80 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
30c90 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
30ca0 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
30cb0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
30cc0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
30cd0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
30ce0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
30cf0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
30d00 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
30d10 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
30d20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
30d30 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33  lue_type(sqlite3
30d40 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
30d50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
30d60 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33  ric_type(sqlite3
30d70 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
30d80 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
30d90 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
30da0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31  tion Context {H1
30db0 36 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6210} <S20200>.*
30dc0 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65  *.** The impleme
30dd0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65  ntation of aggre
30de0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
30df0 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74  ns use this rout
30e00 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a  ine to allocate.
30e10 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66  ** a structure f
30e20 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
30e30 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   state..**.** Th
30e40 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
30e50 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
30e60 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75  te_context() rou
30e70 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66  tine is called f
30e80 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c  or a.** particul
30e90 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51  ar aggregate, SQ
30ea0 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e  Lite allocates n
30eb0 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c  Bytes of memory,
30ec0 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
30ed0 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  .** memory, and 
30ee0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
30ef0 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f  r to it. On seco
30f00 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
30f10 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
30f20 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
30f30 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
30f40 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
30f50 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c   function index,
30f60 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
30f70 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
30f80 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
30f90 69 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65  ion of the aggre
30fa0 67 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20  gate can use.** 
30fb0 74 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66  the returned buf
30fc0 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74  fer to accumulat
30fd0 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51  e data..**.** SQ
30fe0 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
30ff0 6c 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c  ly frees the all
31000 6f 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68  ocated buffer wh
31010 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
31020 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  .** query conclu
31030 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
31040 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73  irst parameter s
31050 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20  hould be a copy 
31060 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
31070 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
31080 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
31090 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
310a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
310b0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
310c0 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
310d0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
310e0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
310f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
31100 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
31110 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
31120 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
31130 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
31140 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
31150 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
31160 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
31170 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20 54 68 65  .** {H16211} The
31180 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f   first invocatio
31190 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67  n of [sqlite3_ag
311a0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
311b0 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20  C,N)] for.**    
311c0 20 20 20 20 20 20 61 20 70 61 72 74 69 63 75 6c        a particul
311d0 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61  ar instance of a
311e0 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  n aggregate func
311f0 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74  tion (for a part
31200 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20  icular.**       
31210 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61     context C) ca
31220 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61  uses SQLite to a
31230 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74 65 73 20  llocate N bytes 
31240 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20  of memory,.**   
31250 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61 74         zero that
31260 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
31270 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  urn a pointer to
31280 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 6d   the allocated m
31290 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  emory..**.** {H1
312a0 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72  6213} If a memor
312b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
312c0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
312d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
312e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
312f0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 68  context(C,N)] th
31300 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
31310 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a  returns 0..**.**
31320 20 7b 48 31 36 32 31 35 7d 20 53 65 63 6f 6e 64   {H16215} Second
31330 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
31340 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a  invocations of.*
31350 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
31360 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
31370 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20  ntext(C,N)] for 
31380 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78 74  the same context
31390 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20   pointer C.**   
313a0 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74 68         ignore th
313b0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61 6e  e N parameter an
313c0 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74  d return a point
313d0 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a  er to the same.*
313e0 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63 6b  *          block
313f0 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 72   of memory retur
31400 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ned by the first
31410 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
31420 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54 68 65 20  ** {H16217} The 
31430 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
31440 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67 67   by [sqlite3_agg
31450 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
31460 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20  ,N)] is.**      
31470 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c      automaticall
31480 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20 6e  y freed on the n
31490 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ext call to [sql
314a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
314b0 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
314c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
314d0 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  ] for the [prepa
314e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 63  red statement] c
314f0 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20  ontaining.**    
31500 20 20 20 20 20 20 74 68 65 20 61 67 67 72 65 67        the aggreg
31510 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 73  ate function ass
31520 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f 6e  ociated with con
31530 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20  text C..*/.void 
31540 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
31550 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
31560 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
31570 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
31580 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
31590 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
315a0 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c 53 32 30  ns {H16240} <S20
315b0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  200>.**.** The s
315c0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
315d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
315e0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
315f0 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
31600 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
31610 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
31620 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
31630 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
31640 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31650 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
31660 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31670 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
31680 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
31690 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
316a0 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
316b0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
316c0 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ction. {END}.**.
316d0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
316e0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
316f0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
31700 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
31710 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
31720 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
31730 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
31740 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
31750 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d 20 54 68  *.** {H16243} Th
31760 65 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  e [sqlite3_user_
31770 64 61 74 61 28 43 29 5d 20 69 6e 74 65 72 66 61  data(C)] interfa
31780 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
31790 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  y of the.**     
317a0 20 20 20 20 20 50 20 70 6f 69 6e 74 65 72 20 66       P pointer f
317b0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
317c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
317d0 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
317e0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
317f0 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
31800 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58  e_function16(D,X
31810 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63  ,N,E,P,F,S,L)] c
31820 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20  all that.**     
31830 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
31840 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
31850 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
31860 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
31870 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  t] C..*/.void *s
31880 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
31890 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
318a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
318b0 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
318c0 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
318d0 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20  ctions {H16250} 
318e0 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e  <S60600><S20200>
318f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
31900 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
31910 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
31920 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
31930 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
31940 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
31950 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
31960 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
31970 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
31980 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31990 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
319a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
319b0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
319c0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
319d0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
319e0 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
319f0 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
31a00 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ction..**.** INV
31a10 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
31a20 48 31 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c  H16253} The [sql
31a30 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
31a40 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72  handle(C)] inter
31a50 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
31a60 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  opy of the.**   
31a70 20 20 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72         D pointer
31a80 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
31a90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31aa0 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  on(D,X,N,E,P,F,S
31ab0 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,L)].**         
31ac0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
31ad0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44  ate_function16(D
31ae0 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
31af0 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20   call that.**   
31b00 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
31b10 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
31b20 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  on associated wi
31b30 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  th [sqlite3_cont
31b40 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74  ext] C..*/.sqlit
31b50 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74  e3 *sqlite3_cont
31b60 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  ext_db_handle(sq
31b70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
31b80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31b90 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c  : Function Auxil
31ba0 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 32 37  iary Data {H1627
31bb0 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a  0} <S20200>.**.*
31bc0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
31bd0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
31be0 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
31bf0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
31c00 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
31c10 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
31c20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
31c30 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
31c40 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
31c50 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
31c60 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
31c70 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
31c80 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
31c90 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
31ca0 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
31cb0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
31cc0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
31cd0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
31ce0 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
31cf0 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
31d00 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
31d10 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
31d20 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
31d30 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
31d40 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
31d50 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
31d60 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
31d70 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
31d80 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
31d90 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
31da0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
31db0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
31dc0 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
31dd0 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
31de0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
31df0 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
31e00 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
31e10 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
31e20 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
31e30 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
31e40 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
31e50 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
31e60 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
31e70 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
31e80 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
31e90 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
31ea0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
31eb0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
31ec0 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
31ed0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
31ee0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
31ef0 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
31f00 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
31f10 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
31f20 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
31f30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31f40 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20  function. If no 
31f50 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
31f60 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73  n ever.** been s
31f70 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61  et for the Nth a
31f80 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66  rgument of the f
31f90 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74  unction, or if t
31fa0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
31fb0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  .** function par
31fc0 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67  ameter has chang
31fd0 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74  ed since the met
31fe0 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a  a-data was set,.
31ff0 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
32000 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65  get_auxdata() re
32010 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
32020 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
32030 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32040 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
32050 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61  saves the metada
32060 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ta.** pointed to
32070 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61   by its 3rd para
32080 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74  meter as the met
32090 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  adata for the N-
320a0 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
320b0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
320c0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
320d0 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a  on.  Subsequent.
320e0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
320f0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
32100 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74  ) might return t
32110 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20  his data, if it 
32120 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20  has.** not been 
32130 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66  destroyed..** If
32140 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c   it is not NULL,
32150 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
32160 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
32170 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67  or.** function g
32180 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20  iven by the 4th 
32190 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
321a0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
321b0 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74  () on.** the met
321c0 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63  adata when the c
321d0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
321e0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
321f0 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68  changes.** or wh
32200 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
32210 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20  ment completes, 
32220 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
32230 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  first..**.** SQL
32240 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63  ite is free to c
32250 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74  all the destruct
32260 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61  or and drop meta
32270 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70  data on any.** p
32280 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20  arameter of any 
32290 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20  function at any 
322a0 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20  time.  The only 
322b0 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61  guarantee is tha
322c0 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63  t.** the destruc
322d0 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c  tor will be call
322e0 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65  ed before the me
322f0 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65  tadata is droppe
32300 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63  d..**.** In prac
32310 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
32320 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
32330 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
32340 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73  ls for.** expres
32350 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63  sions that are c
32360 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69  onstant at compi
32370 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e  le time. This in
32380 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a  cludes literal.*
32390 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c  * values and SQL
323a0 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a   variables..**.*
323b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
323c0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
323d0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
323e0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
323f0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32400 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
32410 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
32420 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32 7d 20 54  **.** {H16272} T
32430 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  he [sqlite3_get_
32440 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e  auxdata(C,N)] in
32450 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
32460 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20  a pointer.**    
32470 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64 61 74        to metadat
32480 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
32490 68 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65  h the Nth parame
324a0 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ter of the SQL f
324b0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  unction.**      
324c0 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74 65 78      whose contex
324d0 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20  t is C, or NULL 
324e0 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  if there is no m
324f0 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
32500 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ed.**          w
32510 69 74 68 20 74 68 61 74 20 70 61 72 61 6d 65 74  ith that paramet
32520 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37  er..**.** {H1627
32530 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
32540 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
32550 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  P,D)] interface 
32560 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61 64 61  assigns a metada
32570 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  ta.**          p
32580 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68 65 20  ointer P to the 
32590 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  Nth parameter of
325a0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
325b0 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43  n with context C
325c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 36 7d  ..**.** {H16276}
325d0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
325e0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
325f0 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67  or D with a sing
32600 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20  le argument.**  
32610 20 20 20 20 20 20 20 20 77 68 69 63 68 20 69 73          which is
32620 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f   the metadata po
32630 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e  inter P followin
32640 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20  g a call to.**  
32650 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
32660 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
32670 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69  ,P,D)] when SQLi
32680 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c  te ceases to hol
32690 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  d.**          th
326a0 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a  e metadata..**.*
326b0 2a 20 7b 48 31 36 32 37 37 7d 20 53 51 4c 69 74  * {H16277} SQLit
326c0 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64  e ceases to hold
326d0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e   metadata for an
326e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61   SQL function pa
326f0 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20  rameter.**      
32700 20 20 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c      when the val
32710 75 65 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d  ue of that param
32720 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a  eter changes..**
32730 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20 57 68 65  .** {H16278} Whe
32740 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  n [sqlite3_set_a
32750 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d  uxdata(C,N,P,D)]
32760 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65   is invoked, the
32770 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20   destructor.**  
32780 20 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65          is calle
32790 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20  d for any prior 
327a0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
327b0 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d  ted with the sam
327c0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  e function.**   
327d0 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43         context C
327e0 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e   and parameter N
327f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 39 7d  ..**.** {H16279}
32800 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c   SQLite will cal
32810 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f  l destructors fo
32820 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69  r any metadata i
32830 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20  t is holding.** 
32840 20 20 20 20 20 20 20 20 20 69 6e 20 61 20 70 61           in a pa
32850 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72  rticular [prepar
32860 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
32870 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20  when either.**  
32880 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
32890 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73  _reset(S)] or [s
328a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
328b0 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a  S)] is called..*
328c0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
328d0 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
328e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
328f0 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t N);.void sqlit
32900 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
32910 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32920 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
32930 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
32940 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
32950 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
32960 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
32970 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
32980 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31  r {H10280} <S301
32990 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
329a0 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
329b0 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
329c0 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
329d0 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
329e0 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
329f0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
32a00 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
32a10 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74  t_blob()].  If t
32a20 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
32a30 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
32a40 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
32a50 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
32a60 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
32a70 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
32a80 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
32a90 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
32aa0 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
32ab0 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53  royed.  The.** S
32ac0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
32ad0 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
32ae0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
32af0 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
32b00 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
32b10 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
32b20 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
32b30 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
32b40 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
32b50 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
32b60 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
32b70 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
32b80 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
32b90 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
32ba0 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
32bb0 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20  C++ compilers.  
32bc0 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31  See ticket #2191
32bd0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
32be0 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
32bf0 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
32c00 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
32c10 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
32c20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
32c30 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
32c40 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
32c50 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
32c60 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
32c70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
32c80 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
32c90 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
32ca0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31  SQL Function {H1
32cb0 36 34 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6400} <S20200>.*
32cc0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
32cd0 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
32ce0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
32cf0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
32d00 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
32d10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
32d20 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
32d30 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
32d40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
32d50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
32d60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
32d70 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
32d80 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
32d90 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
32da0 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
32db0 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
32dc0 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
32dd0 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
32de0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
32df0 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
32e00 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
32e10 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
32e20 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
32e30 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
32e40 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
32e50 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
32e60 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
32e70 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
32e80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
32e90 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
32ea0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
32eb0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
32ec0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32ed0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
32ee0 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
32ef0 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
32f00 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
32f10 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
32f20 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
32f30 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
32f40 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
32f50 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
32f60 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
32f70 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
32f80 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
32f90 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
32fa0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
32fb0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
32fc0 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
32fd0 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
32fe0 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
32ff0 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
33000 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
33010 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
33020 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  rameter..**.** T
33030 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33040 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72  t_double() inter
33050 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
33060 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
33070 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33080 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
33090 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  be a floating po
330a0 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66  int value specif
330b0 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e  ied.** by its 2n
330c0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
330d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
330e0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
330f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33100 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
33110 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
33120 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
33130 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
33140 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
33150 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
33160 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
33170 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
33180 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
33190 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
331a0 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
331b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
331c0 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
331d0 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
331e0 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20  essage.  SQLite 
331f0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
33200 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
33210 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
33220 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33230 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c  () as UTF-8. SQL
33240 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
33250 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
33260 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
33270 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
33280 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
33290 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49  * byte order.  I
332a0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
332b0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
332c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
332d0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
332e0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
332f0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
33300 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
33310 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
33320 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
33330 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
33340 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
33350 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69  r..** If the thi
33360 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
33370 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33380 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
33390 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
333a0 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
333b0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
333c0 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
333d0 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
333e0 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
333f0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
33400 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
33410 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20  message..** The 
33420 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33430 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
33440 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
33450 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
33460 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
33470 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
33480 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
33490 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
334a0 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
334b0 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
334c0 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
334d0 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
334e0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
334f0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
33500 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71   harm..** The sq
33510 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33520 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
33530 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
33540 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
33550 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
33560 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
33570 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
33580 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75  ction.  By defau
33590 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
335a0 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
335b0 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71  ERROR.  A subseq
335c0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
335d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
335e0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
335f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
33600 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
33610 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
33620 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
33630 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
33640 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  lt_toobig() inte
33650 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
33660 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
33670 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
33680 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
33690 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20  g or BLOB is to 
336a0 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
336b0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
336c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65  ite3_result_nome
336d0 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
336e0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
336f0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
33700 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
33710 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
33720 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
33730 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
33740 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
33750 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
33760 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
33770 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
33780 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33790 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
337a0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
337b0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
337c0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
337d0 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71  ument..** The sq
337e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
337f0 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
33800 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
33810 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
33820 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33830 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
33840 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
33850 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
33860 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
33870 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
33880 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
33890 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
338a0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
338b0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
338c0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
338d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
338e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
338f0 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  L..**.** The sql
33900 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33910 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
33920 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
33930 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33940 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
33950 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33960 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
33970 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
33980 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
33990 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
339a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
339b0 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
339c0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
339d0 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
339e0 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
339f0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
33a00 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
33a10 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
33a20 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
33a30 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
33a40 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
33a50 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
33a60 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
33a70 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
33a80 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
33a90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33aa0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
33ab0 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  es..** If the 3r
33ac0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
33ad0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33ae0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
33af0 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
33b00 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
33b10 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
33b20 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
33b30 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
33b40 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
33b50 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
33b60 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
33b70 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
33b80 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
33b90 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
33ba0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
33bb0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
33bc0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
33bd0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
33be0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
33bf0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
33c00 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
33c10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33c20 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
33c30 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  ion result..** I
33c40 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
33c50 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
33c60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
33c70 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
33c80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33c90 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
33ca0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
33cb0 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
33cc0 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
33cd0 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
33ce0 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
33cf0 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
33d00 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
33d10 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
33d20 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
33d30 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
33d40 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
33d50 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
33d60 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69  faces or.** sqli
33d70 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
33d80 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
33d90 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
33da0 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
33db0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
33dc0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
33dd0 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
33de0 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
33df0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
33e00 63 6f 70 79 20 74 68 65 20 69 74 20 6f 72 20 63  copy the it or c
33e10 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
33e20 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
33e30 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
33e40 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74   result..** If t
33e50 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
33e60 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
33e70 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
33e80 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
33e90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
33ea0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
33eb0 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
33ec0 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
33ed0 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
33ee0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
33ef0 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
33f00 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
33f10 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
33f20 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
33f30 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
33f40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
33f50 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
33f60 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
33f70 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
33f80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33f90 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
33fa0 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
33fb0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
33fc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
33fd0 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
33fe0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
33ff0 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ter.  The.** sql
34000 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
34010 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
34020 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
34030 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
34040 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
34050 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34060 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
34070 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
34080 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
34090 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
340a0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
340b0 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
340c0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
340d0 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73  * A [protected s
340e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
340f0 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
34100 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
34110 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
34120 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
34130 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
34140 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
34150 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
34160 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
34170 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
34180 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
34190 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
341a0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
341b0 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
341c0 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
341d0 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
341e0 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
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 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
34220 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
34230 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
34240 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
34250 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
34260 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
34270 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20 54 68 65  .** {H16403} The
34280 20 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20   default return 
34290 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53  value from any S
342a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e  QL function is N
342b0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ULL..**.** {H164
342c0 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
342d0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
342e0 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
342f0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
34300 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
34310 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
34320 6e 20 43 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  n C to be a BLOB
34330 20 74 68 61 74 20 69 73 20 4e 20 62 79 74 65 73   that is N bytes
34340 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
34350 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20  length and with 
34360 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20  content pointed 
34370 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  to by V..**.** {
34380 48 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c  H16409} The [sql
34390 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
343a0 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61  le(C,V)] interfa
343b0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a  ce changes the.*
343c0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
343d0 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74  n value of funct
343e0 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20  ion C to be the 
343f0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
34400 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48  alue V..**.** {H
34410 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  16412} The [sqli
34420 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34430 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61  (C,V,N)] interfa
34440 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
34450 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
34460 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74    value of funct
34470 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
34480 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
34490 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
344a0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
344b0 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 38 20  OR] and a UTF-8 
344c0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f  error message co
344d0 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74  pied from V up t
344e0 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
344f0 20 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74    first zero byt
34500 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74  e or until N byt
34510 65 73 20 61 72 65 20 72 65 61 64 20 69 66 20 4e  es are read if N
34520 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a   is positive..**
34530 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20 54 68 65  .** {H16415} The
34540 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
34550 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d  _error16(C,V,N)]
34560 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
34570 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
34580 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
34590 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
345a0 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
345b0 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
345c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
345d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20  LITE_ERROR] and 
345e0 61 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  a UTF-16 native 
345f0 62 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72  byte order error
34600 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20   message.**     
34610 20 20 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d       copied from
34620 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
34630 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
34640 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79  or or until N by
34650 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
34660 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69 73  are read if N is
34670 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a   positive..**.**
34680 20 7b 48 31 36 34 31 38 7d 20 54 68 65 20 5b 73   {H16418} The [s
34690 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
346a0 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69  ror_toobig(C)] i
346b0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
346c0 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
346d0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
346e0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20   the function C 
346f0 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
34700 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
34710 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  de.**          [
34720 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61  SQLITE_TOOBIG] a
34730 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  nd an appropriat
34740 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
34750 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 31 7d 20  .**.** {H16421} 
34760 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
34770 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
34780 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  C)] interface ch
34790 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
347a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
347b0 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  ue of the functi
347c0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78  on C to be an ex
347d0 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72  ception with err
347e0 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
347f0 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45      [SQLITE_NOME
34800 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70  M] and an approp
34810 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73  riate error mess
34820 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  age..**.** {H164
34830 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  24} The [sqlite3
34840 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f  _result_error_co
34850 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61  de(C,E)] interfa
34860 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
34870 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
34880 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66    value of the f
34890 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
348a0 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74  an exception wit
348b0 68 20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a  h error code E..
348c0 2a 2a 20 20 20 20 20 20 20 20 20 20 54 68 65 20  **          The 
348d0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
348e0 78 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  xt is unchanged.
348f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 37 7d 20  .**.** {H16427} 
34900 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
34910 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e  ult_int(C,V)] in
34920 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
34930 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
34940 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
34950 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
34960 20 74 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65   the 32-bit inte
34970 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a  ger value V..**.
34980 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54 68 65 20  ** {H16430} The 
34990 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
349a0 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65  int64(C,V)] inte
349b0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
349c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
349d0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
349e0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
349f0 68 65 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  he 64-bit intege
34a00 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  r value V..**.**
34a10 20 7b 48 31 36 34 33 33 7d 20 54 68 65 20 5b 73   {H16433} The [s
34a20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
34a30 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ll(C)] interface
34a40 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
34a50 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
34a60 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
34a70 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  n C to be NULL..
34a80 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36 7d 20 54  **.** {H16436} T
34a90 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
34aa0 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29  lt_text(C,V,N,D)
34ab0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
34ac0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
34ad0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
34ae0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
34af0 6f 20 62 65 20 74 68 65 20 55 54 46 2d 38 20 73  o be the UTF-8 s
34b00 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
34b10 20 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69    V up to the fi
34b20 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73  rst zero if N is
34b30 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20   negative.**    
34b40 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72        or the fir
34b50 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20  st N bytes of V 
34b60 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  if N is non-nega
34b70 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tive..**.** {H16
34b80 34 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  439} The [sqlite
34b90 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
34ba0 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
34bb0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
34bc0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
34bd0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
34be0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
34bf0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
34c00 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
34c10 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75        string V u
34c20 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
34c30 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61  ero if N is nega
34c40 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
34c50 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20   or the first N 
34c60 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20  bytes of V if N 
34c70 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
34c80 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 32 7d 20  .**.** {H16442} 
34c90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
34ca0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56  ult_text16be(C,V
34cb0 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,N,D)] interface
34cc0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
34cd0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
34ce0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
34cf0 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54  n C to be the UT
34d00 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a  F-16 big-endian.
34d10 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
34d20 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66  ng V up to the f
34d30 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69  irst zero if N i
34d40 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20  s negative.**   
34d50 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69         or the fi
34d60 72 73 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56  rst N bytes or V
34d70 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67   if N is non-neg
34d80 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
34d90 36 34 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  6445} The [sqlit
34da0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
34db0 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74  le(C,V,N,D)] int
34dc0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
34dd0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
34de0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
34df0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
34e00 74 68 65 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  the UTF-16 littl
34e10 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20  e-endian.**     
34e20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70       string V up
34e30 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
34e40 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  ro if N is negat
34e50 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
34e60 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62  or the first N b
34e70 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69  ytes of V if N i
34e80 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a  s non-negative..
34e90 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38 7d 20 54  **.** {H16448} T
34ea0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
34eb0 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20 69  lt_value(C,V)] i
34ec0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
34ed0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
34ee0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
34ef0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
34f00 65 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  e the [unprotect
34f10 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
34f20 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  ].**          ob
34f30 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ject V..**.** {H
34f40 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69  16451} The [sqli
34f50 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
34f60 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66  lob(C,N)] interf
34f70 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
34f80 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
34f90 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
34fa0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
34fb0 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f 66 20 61  N-byte BLOB of a
34fc0 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20  ll zeros..**.** 
34fd0 7b 48 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71  {H16454} The [sq
34fe0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
34ff0 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  or()] and [sqlit
35000 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
35010 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  6()].**         
35020 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65   interfaces make
35030 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72   a copy of their
35040 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
35050 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a  trings before.**
35060 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
35070 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ing..**.** {H164
35080 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 65 73  57} If the D des
35090 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65  tructor paramete
350a0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  r to [sqlite3_re
350b0 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c  sult_blob(C,V,N,
350c0 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
350d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
350e0 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _text(C,V,N,D)],
350f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35100 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
35110 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
35120 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35130 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29  ext16be(C,V,N,D)
35140 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
35150 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
35160 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
35170 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73  ,D)] is the cons
35180 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
35190 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  TIC].**         
351a0 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63   then no destruc
351b0 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c  tor is ever call
351c0 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65  ed on the pointe
351d0 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a  r V and SQLite.*
351e0 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 75 6d  *          assum
351f0 65 73 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d  es that V is imm
35200 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  utable..**.** {H
35210 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 44 20  16460} If the D 
35220 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d  destructor param
35230 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
35240 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
35250 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
35260 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
35270 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
35280 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  )], [sqlite3_res
35290 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e  ult_text16(C,V,N
352a0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
352b0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
352c0 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
352d0 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
352e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
352f0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
35300 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63  V,N,D)] is the c
35310 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20  onstant.**      
35320 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e      [SQLITE_TRAN
35330 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20  SIENT] then the 
35340 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73  interfaces makes
35350 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
35360 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65  *          conte
35370 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61  nt of V and reta
35380 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a  ins the copy..**
35390 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20 49 66 20  .** {H16463} If 
353a0 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72  the D destructor
353b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
353c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
353d0 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  ob(C,V,N,D)],.**
353e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
353f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43  e3_result_text(C
35400 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74  ,V,N,D)], [sqlit
35410 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35420 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
35430 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
35440 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
35450 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a  (C,V,N,D)], or.*
35460 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
35470 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
35480 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73  6le(C,V,N,D)] is
35490 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65   some value othe
354a0 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  r than.**       
354b0 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73     the constants
354c0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
354d0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41   and [SQLITE_TRA
354e0 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a 20  NSIENT] then.** 
354f0 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20           SQLite 
35500 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
35510 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74  destructor D wit
35520 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79 20  h V as its only 
35530 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20  argument.**     
35540 20 20 20 20 20 77 68 65 6e 20 69 74 20 68 61 73       when it has
35550 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
35560 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76  he V value..*/.v
35570 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35580 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
35590 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
355a0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
355b0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
355c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
355d0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
355e0 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65  context*, double
355f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
35600 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c  result_error(sql
35610 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35620 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
35630 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35640 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
35650 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35660 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
35670 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
35680 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
35690 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
356a0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
356b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
356c0 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63  _nomem(sqlite3_c
356d0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
356e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
356f0 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33  ror_code(sqlite3
35700 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
35710 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35720 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
35730 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
35740 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35750 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
35760 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
35770 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69  ite3_int64);.voi
35780 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35790 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
357a0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
357b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
357c0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
357d0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
357e0 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
357f0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
35800 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
35810 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
35820 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
35830 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
35840 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
35850 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
35860 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
35870 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
35880 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
35890 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
358a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
358b0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
358c0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
358d0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
358e0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
358f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
35900 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
35910 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
35920 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
35930 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
35940 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
35950 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
35960 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
35970 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
35980 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31  ng Sequences {H1
35990 36 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a  6600} <S20300>.*
359a0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
359b0 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f  ions are used to
359c0 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69   add new collati
359d0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20  on sequences to 
359e0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
359f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
35a00 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
35a10 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
35a20 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
35a30 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  the new collatio
35a40 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70  n sequence is sp
35a50 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46  ecified as a UTF
35a60 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
35a70 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35a80 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
35a90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
35aa0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
35ab0 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
35ac0 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33  ring for sqlite3
35ad0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35ae0 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61  n16(). In all ca
35af0 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  ses.** the name 
35b00 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  is passed as the
35b10 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
35b20 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
35b30 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
35b40 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ent may be one o
35b50 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20  f the constants 
35b60 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
35b70 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
35b80 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  E] or [SQLITE_UT
35b90 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16BE], indicati
35ba0 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72  ng that the user
35bb0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75  -supplied.** rou
35bc0 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20  tine expects to 
35bd0 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65  be passed pointe
35be0 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e  rs to strings en
35bf0 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
35c00 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  8,.** UTF-16 lit
35c10 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle-endian, or U
35c20 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
35c30 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
35c40 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67  The.** third arg
35c50 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f  ument might also
35c60 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
35c70 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e  6_ALIGNED] to in
35c80 64 69 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74  dicate that.** t
35c90 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63  he routine expec
35ca0 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31  ts pointers to 1
35cb0 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e  6-bit word align
35cc0 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66  ed strings.** of
35cd0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
35ce0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
35cf0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d   of the host com
35d00 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70  puter..**.** A p
35d10 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73  ointer to the us
35d20 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74  er supplied rout
35d30 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73  ine must be pass
35d40 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a  ed as the fifth.
35d50 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66  ** argument.  If
35d60 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69   it is NULL, thi
35d70 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  s is the same as
35d80 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
35d90 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
35da0 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c  nce (so that SQL
35db0 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20  ite cannot call 
35dc0 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20  it anymore)..** 
35dd0 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70  Each time the ap
35de0 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69  plication suppli
35df0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  ed function is i
35e00 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61  nvoked, it is pa
35e10 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66  ssed.** as its f
35e20 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61  irst parameter a
35e30 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
35e40 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  d* passed as the
35e50 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
35e60 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
35e70 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
35e80 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
35e90 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
35ea0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d  )..**.** The rem
35eb0 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73  aining arguments
35ec0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
35ed0 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75  ion-supplied rou
35ee0 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72  tine are two str
35ef0 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65  ings,.** each re
35f00 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28  presented by a (
35f10 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61  length, data) pa
35f20 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69  ir and encoded i
35f30 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a  n the encoding.*
35f40 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65  * that was passe
35f50 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61  d as the third a
35f60 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65  rgument when the
35f70 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
35f80 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73  nce was.** regis
35f90 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68  tered. {END}  Th
35fa0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
35fb0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
35fc0 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a  routine should.*
35fd0 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76  * return negativ
35fe0 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74  e, zero or posit
35ff0 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73 74  ive if the first
36000 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
36010 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74  than,.** equal t
36020 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  o, or greater th
36030 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74  an the second st
36040 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49  ring. i.e. (STRI
36050 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a  NG1 - STRING2)..
36060 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
36070 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36080 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
36090 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
360a0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
360b0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
360c0 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61  takes an extra a
360d0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
360e0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
360f0 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  r.** the collati
36100 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  on.  The destruc
36110 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68  tor is called wh
36120 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
36130 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64   is.** destroyed
36140 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61   and is passed a
36150 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75   copy of the fou
36160 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f  rth parameter vo
36170 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f  id* pointer.** o
36180 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72  f the sqlite3_cr
36190 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
361a0 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f  2()..** Collatio
361b0 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  ns are destroyed
361c0 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f   when they are o
361d0 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
361e0 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  er calls to the.
361f0 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  ** collation cre
36200 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
36210 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74  or when the [dat
36220 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36230 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75  ] is closed.** u
36240 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
36250 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ose()]..**.** IN
36260 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
36270 7b 48 31 36 36 30 33 7d 20 41 20 73 75 63 63 65  {H16603} A succe
36280 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68  ssful call to th
36290 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
362a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
362b0 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
362c0 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,P,F,D)] interfa
362d0 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ce.**          r
362e0 65 67 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f  egisters functio
362f0 6e 20 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61  n F as the compa
36300 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75  rison function u
36310 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  sed to.**       
36320 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c     implement col
36330 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74 68 65 20  lation X on the 
36340 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36350 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20  tion] B for.**  
36360 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
36370 73 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e  s having encodin
36380 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  g E..**.** {H166
36390 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72  04} SQLite under
363a0 73 74 61 6e 64 73 20 74 68 65 20 58 20 70 61 72  stands the X par
363b0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
363c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
363d0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
363e0 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
363f0 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   as a zero-termi
36400 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
36410 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69    UTF-8 string i
36420 6e 20 77 68 69 63 68 20 63 61 73 65 20 69 73 20  n which case is 
36430 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49  ignored for ASCI
36440 49 20 63 68 61 72 61 63 74 65 72 73 20 61 6e 64  I characters and
36450 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
36460 73 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20  significant for 
36470 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63  non-ASCII charac
36480 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ters..**.** {H16
36490 36 30 36 7d 20 53 75 63 63 65 73 73 69 76 65 20  606} Successive 
364a0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
364b0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
364c0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
364d0 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D)].**          
364e0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61  with the same va
364f0 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61  lues for B, X, a
36500 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70  nd E, override p
36510 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20  rior values.**  
36520 20 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c          of P, F,
36530 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48   and D..**.** {H
36540 31 36 36 30 39 7d 20 49 66 20 74 68 65 20 64 65  16609} If the de
36550 73 74 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73  structor D in [s
36560 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36570 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
36580 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20  ,P,F,D)].**     
36590 20 20 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c       is not NULL
365a0 20 74 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c   then it is call
365b0 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
365c0 20 50 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20   P when the.**  
365d0 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
365e0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72  g function is dr
365f0 6f 70 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e  opped by SQLite.
36600 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 32 7d 20  .**.** {H16612} 
36610 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  A collating func
36620 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20  tion is dropped 
36630 77 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c  when it is overl
36640 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  oaded..**.** {H1
36650 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e  6615} A collatin
36660 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72  g function is dr
36670 6f 70 70 65 64 20 77 68 65 6e 20 74 68 65 20 64  opped when the d
36680 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36690 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  on.**          i
366a0 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
366b0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
366c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 38 7d  ..**.** {H16618}
366d0 20 54 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69   The pointer P i
366e0 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  n [sqlite3_creat
366f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42  e_collation_v2(B
36700 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20  ,X,E,P,F,D)].** 
36710 20 20 20 20 20 20 20 20 20 69 73 20 70 61 73 73           is pass
36720 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
36730 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
36740 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69  r to the compari
36750 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  son.**          
36760 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61  function F for a
36770 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
36780 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a  vocations of F..
36790 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31 7d 20 41  **.** {H16621} A
367a0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
367b0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
367c0 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69  on(B,X,E,P,F)] i
367d0 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20  s exactly.**    
367e0 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61        the same a
367f0 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  s a call to [sql
36800 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36810 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68  ation_v2()] with
36820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
36830 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73   same parameters
36840 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74   and a NULL dest
36850 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ructor..**.** {H
36860 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67  16624} Following
36870 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61   a [sqlite3_crea
36880 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
36890 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a  B,X,E,P,F,D)],.*
368a0 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74  *          SQLit
368b0 65 20 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61  e uses the compa
368c0 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46  rison function F
368d0 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f   for all text co
368e0 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20  mparison.**     
368f0 20 20 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20       operations 
36900 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
36910 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f   connection] B o
36920 6e 20 74 65 78 74 20 76 61 6c 75 65 73 20 74 68  n text values th
36930 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75  at.**          u
36940 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  se the collating
36950 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 64 20   sequence named 
36960 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 37  X..**.** {H16627
36970 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
36980 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
36990 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f  6(B,X,E,P,F)] wo
369a0 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  rks the same.** 
369b0 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c           as [sql
369c0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
369d0 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29  ation(B,X,E,P,F)
369e0 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
369f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
36a00 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69  llation name X i
36a10 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20  s understood as 
36a20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
36a30 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20   byte order.**  
36a40 20 20 20 20 20 20 20 20 69 6e 73 74 65 61 64 20          instead 
36a50 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  of UTF-8..**.** 
36a60 7b 48 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75  {H16630} When mu
36a70 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f  ltiple compariso
36a80 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  n functions are 
36a90 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68  available for th
36aa0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
36ab0 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71     collating seq
36ac0 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68  uence, SQLite ch
36ad0 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68  ooses the one wh
36ae0 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  ose text encodin
36af0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  g.**          re
36b00 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74  quires the least
36b10 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65   amount of conve
36b20 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64  rsion from the d
36b30 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20  efault.**       
36b40 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67     text encoding
36b50 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
36b60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
36b70 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36b80 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
36b90 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
36ba0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
36bb0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
36bc0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
36bd0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
36be0 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
36bf0 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
36c00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36c10 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
36c20 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
36c30 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
36c40 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
36c50 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
36c60 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
36c70 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
36c80 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
36c90 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
36ca0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
36cb0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
36cc0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
36cd0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
36ce0 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a  st void *zName,.
36cf0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
36d00 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
36d10 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
36d20 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
36d30 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
36d40 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
36d50 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
36d60 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
36d70 20 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30   {H16700} <S2030
36d80 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69  0>.**.** To avoi
36d90 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
36da0 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
36db0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
36dc0 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
36dd0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
36de0 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
36df0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
36e00 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
36e10 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
36e20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
36e30 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65   be called whene
36e40 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
36e50 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
36e60 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72  quence is requir
36e70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
36e80 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
36e90 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
36ea0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
36eb0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
36ec0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
36ed0 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
36ee0 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
36ef0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
36f00 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
36f10 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
36f20 2e 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71  . {H16703} If sq
36f30 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
36f40 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
36f50 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73  ed,.** the names
36f60 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
36f70 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
36f80 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
36f90 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  er..** A call to
36fa0 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
36fb0 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78   replaces any ex
36fc0 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e  isting callback.
36fd0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
36fe0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
36ff0 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
37000 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
37010 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
37020 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
37030 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
37040 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
37050 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
37060 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
37070 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
37080 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
37090 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
370a0 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68  nection.  The th
370b0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
370c0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
370d0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
370e0 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  F16BE],.** or [S
370f0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
37100 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
37110 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
37120 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
37130 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
37140 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
37150 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  d.  The fourth p
37160 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
37170 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
37180 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
37190 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a  n sequence..**.*
371a0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
371b0 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
371c0 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
371d0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
371e0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
371f0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
37200 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
37210 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
37220 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
37230 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37240 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  tion_v2()]..**.*
37250 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
37260 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20 41 20 73  .** {H16702} A s
37270 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
37280 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  o [sqlite3_colla
37290 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c  tion_needed(D,P,
372a0 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F)].**          
372b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  or [sqlite3_coll
372c0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44  ation_needed16(D
372d0 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a  ,P,F)] causes.**
372e0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 64            the [d
372f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37300 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20  on] D to invoke 
37310 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20  callback F with 
37320 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20  first.**        
37330 20 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68    parameter P wh
37340 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73 20  enever it needs 
37350 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e  a comparison fun
37360 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20  ction for a.**  
37370 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e          collatin
37380 67 20 73 65 71 75 65 6e 63 65 20 74 68 61 74 20  g sequence that 
37390 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77  it does not know
373a0 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48   about..**.** {H
373b0 31 36 37 30 34 7d 20 45 61 63 68 20 73 75 63 63  16704} Each succ
373c0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
373d0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
373e0 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a  n_needed()] or.*
373f0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
37400 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37410 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69  eded16()] overri
37420 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  des the callback
37430 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20   registered.**  
37440 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73          on the s
37450 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
37460 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69  nnection] by pri
37470 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68  or calls to eith
37480 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  er.**          i
37490 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
374a0 7b 48 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d  {H16706} The nam
374b0 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73 74  e of the request
374c0 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ed collating fun
374d0 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20  ction passed in 
374e0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
374f0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
37500 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
37510 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65   in UTF-8 if the
37520 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
37530 20 20 20 20 20 20 77 61 73 20 72 65 67 69 73 74        was regist
37540 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ered using [sqli
37550 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37560 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20  eded()] and.**  
37570 20 20 20 20 20 20 20 20 69 73 20 69 6e 20 55 54          is in UT
37580 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
37590 20 6f 72 64 65 72 20 69 66 20 74 68 65 20 63 61   order if the ca
375a0 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20  llback was.**   
375b0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
375c0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
375d0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
375e0 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  d16()]..*/.int s
375f0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37600 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
37610 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
37620 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
37630 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
37640 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
37650 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
37660 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37670 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
37680 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
37690 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
376a0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
376b0 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
376c0 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
376d0 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
376e0 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
376f0 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
37700 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
37710 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
37720 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
37730 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
37740 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
37750 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
37760 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
37770 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
37780 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
37790 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
377a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
377b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
377c0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
377d0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
377e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
377f0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
37800 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
37810 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
37820 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
37830 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
37840 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
37850 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
37860 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
37870 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
37880 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
37890 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
378a0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
378b0 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
378c0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
378d0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
378e0 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
378f0 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
37900 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
37910 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
37920 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
37930 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
37940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
37950 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
37960 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
37970 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
37980 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
37990 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
379a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
379b0 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
379c0 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
379d0 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53  Time {H10530} <S
379e0 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  40410>.**.** The
379f0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
37a00 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
37a10 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
37a20 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65  ead to suspend e
37a30 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  xecution.** for 
37a40 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65  at least a numbe
37a50 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
37a60 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69  s specified in i
37a70 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ts parameter..**
37a80 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61  .** If the opera
37a90 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73  ting system does
37aa0 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65   not support sle
37ab0 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68  ep requests with
37ac0 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20  .** millisecond 
37ad0 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  time resolution,
37ae0 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77   then the time w
37af0 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75  ill be rounded u
37b00 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72  p to.** the near
37b10 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20  est second. The 
37b20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
37b30 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20  econds of sleep 
37b40 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75  actually.** requ
37b50 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f  ested from the o
37b60 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
37b70 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
37b80 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
37b90 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
37ba0 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
37bb0 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
37bc0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
37bd0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
37be0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  s] object..**.**
37bf0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
37c00 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54 68 65 20  ** {H10533} The 
37c10 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d  [sqlite3_sleep(M
37c20 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76  )] interface inv
37c30 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a  okes the xSleep.
37c40 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 74 68  **          meth
37c50 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
37c60 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56  t [sqlite3_vfs|V
37c70 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  FS] in order to.
37c80 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 73 70  **          susp
37c90 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  end execution of
37ca0 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72   the current thr
37cb0 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74  ead for at least
37cc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d  .**          M m
37cd0 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a  illiseconds..**.
37ce0 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54 68 65 20  ** {H10536} The 
37cf0 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d  [sqlite3_sleep(M
37d00 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
37d10 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
37d20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  of.**          m
37d30 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
37d40 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65  leep actually re
37d50 71 75 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f  quested of the o
37d60 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20  perating.**     
37d70 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69       system, whi
37d80 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67  ch might be larg
37d90 65 72 20 74 68 61 6e 20 74 68 65 20 70 61 72 61  er than the para
37da0 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20  meter M..*/.int 
37db0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
37dc0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
37dd0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
37de0 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
37df0 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20  Temporary Files 
37e00 7b 48 31 30 33 31 30 7d 20 3c 53 32 30 30 30 30  {H10310} <S20000
37e10 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20  >.**.** If this 
37e20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
37e30 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
37e40 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
37e50 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
37e60 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
37e70 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
37e80 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
37e90 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
37ea0 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
37eb0 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69  will be placed i
37ec0 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79  n that directory
37ed0 2e 20 20 49 66 20 74 68 69 73 20 76 61 72 69 61  .  If this varia
37ee0 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ble.** is a NULL
37ef0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
37f00 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61  QLite performs a
37f10 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
37f20 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65  ppropriate.** te
37f30 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72  mporary file dir
37f40 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
37f50 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
37f60 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
37f70 61 62 6c 65 20 6f 6e 63 65 20 61 20 5b 64 61 74  able once a [dat
37f80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37f90 5d 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f 70  ].** has been op
37fa0 65 6e 65 64 2e 20 20 49 74 20 69 73 20 69 6e 74  ened.  It is int
37fb0 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
37fc0 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
37fd0 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
37fe0 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
37ff0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
38000 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
38010 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
38020 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
38030 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20  call and remain 
38040 75 6e 63 68 61 6e 67 65 64 20 74 68 65 72 65 61  unchanged therea
38050 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  fter..*/.SQLITE_
38060 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c  EXTERN char *sql
38070 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
38080 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
38090 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41  3REF: Test For A
380a0 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20  uto-Commit Mode 
380b0 7b 48 31 32 39 33 30 7d 20 3c 53 36 30 32 30 30  {H12930} <S60200
380c0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
380d0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d  autocommit mode}
380e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
380f0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
38100 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
38110 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
38120 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
38130 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
38140 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
38150 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
38160 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
38170 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 75  espectively.  Au
38180 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
38190 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a   on by default..
381a0 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  ** Autocommit mo
381b0 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
381c0 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  y a [BEGIN] stat
381d0 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f  ement..** Autoco
381e0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d  mmit mode is re-
381f0 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f  enabled by a [CO
38200 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
38210 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  CK]..**.** If ce
38220 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
38230 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
38240 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
38250 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
38260 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
38270 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75  on (errors inclu
38280 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c  ding [SQLITE_FUL
38290 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  L], [SQLITE_IOER
382a0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  R],.** [SQLITE_N
382b0 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
382c0 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
382d0 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
382e0 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
382f0 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
38300 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
38310 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
38320 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
38330 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53  nd out whether S
38340 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
38350 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
38360 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
38370 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  after.** an erro
38380 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73  r is to use this
38390 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
383a0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
383b0 2a 2a 20 7b 48 31 32 39 33 31 7d 20 54 68 65 20  ** {H12931} The 
383c0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74  [sqlite3_get_aut
383d0 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74 65  ocommit(D)] inte
383e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
383f0 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20 20  n-zero or.**    
38400 20 20 20 20 20 20 7a 65 72 6f 20 69 66 20 74 68        zero if th
38410 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
38420 65 63 74 69 6f 6e 5d 20 44 20 69 73 20 6f 72 20  ection] D is or 
38430 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
38440 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  mmit.**         
38450 20 6d 6f 64 65 2c 20 72 65 73 70 65 63 74 69 76   mode, respectiv
38460 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ely..**.** {H129
38470 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  32} Autocommit m
38480 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66  ode is on by def
38490 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ault..**.** {H12
384a0 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20  933} Autocommit 
384b0 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
384c0 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c   by a successful
384d0 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65   [BEGIN] stateme
384e0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33  nt..**.** {H1293
384f0 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  4} Autocommit mo
38500 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
38510 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b 43   a successful [C
38520 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
38530 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ACK].**         
38540 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
38550 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
38560 2a 0a 2a 2a 20 7b 41 31 32 39 33 36 7d 20 49 66  *.** {A12936} If
38570 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20   another thread 
38580 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f  changes the auto
38590 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66  commit status of
385a0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
385b0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63            connec
385c0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
385d0 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
385e0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
385f0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  urn value.**    
38600 20 20 20 20 20 20 69 73 20 75 6e 64 65 66 69 6e        is undefin
38610 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
38620 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
38630 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
38640 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
38650 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20  nd The Database 
38660 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70  Handle Of A Prep
38670 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b  ared Statement {
38680 48 31 33 31 32 30 7d 20 3c 53 36 30 36 30 30 3e  H13120} <S60600>
38690 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
386a0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74  e3_db_handle int
386b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
386c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
386d0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a  nection] handle.
386e0 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70  ** to which a [p
386f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
38700 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65  t] belongs.  The
38710 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
38720 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
38730 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
38740 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 64 61  e is the same da
38750 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74 68  tabase handle th
38760 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74  at was the first
38770 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
38780 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
38790 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20  pare_v2()] call 
387a0 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73  (or its variants
387b0 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20  ) that was used 
387c0 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65  to.** create the
387d0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
387e0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
387f0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
38800 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 32 33 7d 20  .**.** {H13123} 
38810 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
38820 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65 72  handle(S)] inter
38830 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
38840 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ointer.**       
38850 20 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62     to the [datab
38860 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
38870 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
38880 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
38890 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
388a0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69 74  ent] S..*/.sqlit
388b0 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68  e3 *sqlite3_db_h
388c0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  andle(sqlite3_st
388d0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
388e0 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20  I3REF: Find the 
388f0 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74  next prepared st
38900 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d  atement {H13140}
38910 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60600>.**.** 
38920 54 68 69 73 20 69 6e 74 65 72