/ Hex Artifact Content
Login

Artifact e5c0dc85b1340f566d977263d4cca7ca32183c34:


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 39 20 32 30 30 38 2f 31  n,v 1.409 2008/1
05f0: 31 2f 30 37 20 30 30 3a 30 36 3a 31 38 20 64 72  1/07 00:06:18 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20  .** These no-op 
0750: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
0760: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65  in front of inte
0770: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74  rfaces to mark t
0780: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hose.** interfac
0790: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70  es as either dep
07a0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72  recated or exper
07b0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70  imental.  New ap
07c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
07d0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70  ould not use dep
07e0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65  recated intrface
07f0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
0800: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72  port for backwar
0810: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
0820: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
0830: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
0840: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
0850: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
0860: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
0870: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0880: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0890: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
08a0: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
08b0: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
08c0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
08d0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
08e0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
08f0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0900: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0910: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
0920: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
0930: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
0940: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
0950: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
0960: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
0970: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0980: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0990: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
09a0: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
09b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
09c0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
09d0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
09e0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
09f0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a00: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a10: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0a20: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0a30: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0a40: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0a50: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0a60: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0a70: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0a80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0a90: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0aa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0ab0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0ac0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0ad0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0ae0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31  n Numbers {H1001
0af0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
0b00: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0b10: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f  SION and SQLITE_
0b20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23  VERSION_NUMBER #
0b30: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68  defines in.** th
0b40: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65  e sqlite3.h file
0b50: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72   specify the ver
0b60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77  sion of SQLite w
0b70: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61  ith which.** tha
0b80: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73  t header file is
0b90: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a   associated..**.
0ba0: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22  ** The "version"
0bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20   of SQLite is a 
0bc0: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f  string of the fo
0bd0: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54  rm "X.Y.Z"..** T
0be0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61  he phrase "alpha
0bf0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68  " or "beta" migh
0c00: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66  t be appended af
0c10: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68  ter the Z..** Th
0c20: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a  e X value is maj
0c30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0c40: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51  r always 3 in SQ
0c50: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20  Lite3..** The X 
0c60: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0c70: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64  es when backward
0c80: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
0c90: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64  is.** broken and
0ca0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65   we intend to ne
0cb0: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61  ver break backwa
0cc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0cd0: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75  y..** The Y valu
0ce0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  e is the minor v
0cf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
0d00: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  d only changes w
0d10: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65  hen.** there are
0d20: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65   major feature e
0d30: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74  nhancements that
0d40: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f   are forwards co
0d50: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20  mpatible.** but 
0d60: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f  not backwards co
0d70: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  mpatible..** The
0d80: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20   Z value is the 
0d90: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61  release number a
0da0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  nd is incremente
0db0: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0dc0: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0dd0: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0de0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d  ever Y is increm
0df0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ented..**.** See
0e00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
0e10: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  libversion()] an
0e20: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  d [sqlite3_libve
0e30: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e  rsion_number()].
0e40: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
0e50: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31  S:.**.** {H10011
0e60: 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  } The SQLITE_VER
0e70: 53 49 4f 4e 20 23 64 65 66 69 6e 65 20 69 6e 20  SION #define in 
0e80: 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65  the sqlite3.h he
0e90: 61 64 65 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a  ader file shall.
0ea0: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 76 61 6c  **          eval
0eb0: 75 61 74 65 20 74 6f 20 61 20 73 74 72 69 6e 67  uate to a string
0ec0: 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73   literal that is
0ed0: 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73   the SQLite vers
0ee0: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
0ef0: 77 69 74 68 20 77 68 69 63 68 20 74 68 65 20 68  with which the h
0f00: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73  eader file is as
0f10: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  sociated..**.** 
0f20: 7b 48 31 30 30 31 34 7d 20 54 68 65 20 53 51 4c  {H10014} The SQL
0f30: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0f40: 45 52 20 23 64 65 66 69 6e 65 20 73 68 61 6c 6c  ER #define shall
0f50: 20 72 65 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69   resolve to an i
0f60: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
0f70: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75     with the valu
0f80: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0f90: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0fa0: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20   X, Y, and Z.** 
0fb0: 20 20 20 20 20 20 20 20 20 61 72 65 20 74 68 65           are the
0fc0: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20   major version, 
0fd0: 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61  minor version, a
0fe0: 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  nd release numbe
0ff0: 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  r..*/.#define SQ
1000: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1010: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
1020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1030: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d  ERSION_NUMBER  -
1040: 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d  -VERSION-NUMBER-
1050: 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  -../*.** CAPI3RE
1060: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
1070: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
1080: 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c 53 36  ers {H10020} <S6
1090: 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0100>.** KEYWORD
10a0: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
10b0: 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  on.**.** These f
10c0: 65 61 74 75 72 65 73 20 70 72 6f 76 69 64 65 20  eatures provide 
10d0: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
10e0: 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c  tion as the [SQL
10f0: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20  ITE_VERSION].** 
1100: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  and [SQLITE_VERS
1110: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66  ION_NUMBER] #def
1120: 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61 64  ines in the head
1130: 65 72 2c 20 62 75 74 20 61 72 65 20 61 73 73 6f  er, but are asso
1140: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
1150: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1160: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
1170: 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75 73   file.  Cautious
1180: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
1190: 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20  ht.** include a 
11a0: 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72 20 61  check in their a
11b0: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 76 65  pplication to ve
11c0: 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c  rify that.** sql
11d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
11e0: 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 73 20  number() always 
11f0: 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1200: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  e.** [SQLITE_VER
1210: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a  SION_NUMBER]..**
1220: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1230: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1240: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1250: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1260: 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74  on as is.** in t
1270: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
1280: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1290: 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e 63 74  tant.  The funct
12a0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 0a  ion is provided.
12b0: 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c  ** for use in DL
12c0: 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65  Ls since DLL use
12d0: 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f  rs usually do no
12e0: 74 20 68 61 76 65 20 64 69 72 65 63 74 20 61 63  t have direct ac
12f0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a  cess to string.*
1300: 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68  * constants with
1310: 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a  in the DLL..**.*
1320: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1330: 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54 68 65  .** {H10021} The
1340: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
1350: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69  sion_number()] i
1360: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72  nterface shall r
1370: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
1380: 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75    an integer equ
1390: 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45  al to [SQLITE_VE
13a0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a  RSION_NUMBER]..*
13b0: 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20 54 68  *.** {H10022} Th
13c0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69  e [sqlite3_versi
13d0: 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  on] string const
13e0: 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69  ant shall contai
13f0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
1400: 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 5b 53  e text of the [S
1410: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73  QLITE_VERSION] s
1420: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
1430: 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  0023} The [sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d  e3_libversion()]
1450: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
1460: 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
1470: 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20     a pointer to 
1480: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72  the [sqlite3_ver
1490: 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e  sion] string con
14a0: 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  stant..*/.SQLITE
14b0: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
14c0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
14d0: 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72  on[];.const char
14e0: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
14f0: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  sion(void);.int 
1500: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1510: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
1520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1530: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1540: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1550: 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 30 31  Threadsafe {H101
1560: 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a  00} <S60100>.**.
1570: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1580: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1590: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
15a0: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
15b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
15c0: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
15d0: 6f 72 20 6d 61 63 72 6f 20 31 20 6f 72 20 32 2c  or macro 1 or 2,
15e0: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
15f0: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1600: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1610: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1620: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1630: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1640: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1650: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1660: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1670: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1680: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1690: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
16a0: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
16b0: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
16c0: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
16d0: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
16e0: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
16f0: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1700: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1710: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1720: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1730: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1740: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1750: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1760: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1770: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1780: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  ** The default b
1790: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
17a0: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
17b0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
17c0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
17d0: 65 20 75 73 65 64 20 62 79 20 61 20 70 72 6f 67  e used by a prog
17e0: 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ram to make sure
17f0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72   that the.** ver
1800: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74  sion of SQLite t
1810: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e  hat it is linkin
1820: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f  g against was co
1830: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
1840: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69  he desired setti
1850: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ng of the [SQLIT
1860: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1870: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cro..**.** This 
1880: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
1890: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f  eports on the co
18a0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78  mpile-time mutex
18b0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74   setting.** of t
18c0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
18d0: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66  DSAFE] flag.  If
18e0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
18f0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49  led with.** SQLI
1900: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20  TE_THREADSAFE=1 
1910: 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65  then mutexes are
1920: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
1930: 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62  ult but.** can b
1940: 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69  e fully or parti
1950: 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73  ally disabled us
1960: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
1970: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
1980: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72  .** with the ver
1990: 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  bs [SQLITE_CONFI
19a0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c  G_SINGLETHREAD],
19b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
19c0: 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a  MULTITHREAD],.**
19d0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
19e0: 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20  IG_MUTEX].  The 
19f0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
1a00: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
1a10: 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20  ows.** only the 
1a20: 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d  default compile-
1a30: 74 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f  time setting, no
1a40: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
1a50: 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61  hanges.** to tha
1a60: 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  t setting..**.**
1a70: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
1a80: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
1a90: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
1aa0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1ab0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  on..**.** INVARI
1ac0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ANTS:.**.** {H10
1ad0: 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  101} The [sqlite
1ae0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1af0: 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72  function shall r
1b00: 65 74 75 72 6e 20 7a 65 72 6f 20 69 66 0a 2a 2a  eturn zero if.**
1b10: 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6f 6e            and on
1b20: 6c 79 20 69 66 20 53 51 4c 69 74 65 20 77 61 73  ly if SQLite was
1b30: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1b40: 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69  utexing code omi
1b50: 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  tted..**.** {H10
1b60: 31 30 32 7d 20 54 68 65 20 76 61 6c 75 65 20 72  102} The value r
1b70: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 5b  eturned by the [
1b80: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1b90: 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  fe()] function.*
1ba0: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
1bb0: 20 72 65 6d 61 69 6e 20 74 68 65 20 73 61 6d 65   remain the same
1bc0: 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f   across calls to
1bd0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
1be0: 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1bf0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76  te3_threadsafe(v
1c00: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
1c10: 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
1c20: 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c  Connection Handl
1c30: 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30 32  e {H12000} <S402
1c40: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1c50: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
1c60: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
1c70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
1c80: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
1c90: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
1ca0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
1cb0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1cc0: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
1cd0: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
1ce0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
1cf0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
1d00: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
1d10: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
1d20: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
1d30: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
1d40: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1d50: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1d60: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
1d70: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
1d80: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
1d90: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
1da0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
1db0: 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 75  ** is its destru
1dc0: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65  ctor.  There are
1dd0: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65   many other inte
1de0: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
1df0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1e00: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
1e10: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1e20: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
1e30: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1e40: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
1e50: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
1e60: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
1e70: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
1e80: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
1e90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
1ea0: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
1eb0: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
1ec0: 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b 48  Integer Types {H
1ed0: 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a  10200} <S10110>.
1ee0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
1ef0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
1f00: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
1f10: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
1f20: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
1f30: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
1f40: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
1f50: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
1f60: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
1f70: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
1f80: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
1f90: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
1fa0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
1fb0: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
1fc0: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
1fd0: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69  ferred type defi
1fe0: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nitions..** The 
1ff0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64  sqlite_int64 and
2000: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
2010: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74  ypes are support
2020: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
2030: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
2040: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e  y only..**.** IN
2050: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2060: 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b 73 71  {H10201} The [sq
2070: 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20  lite_int64] and 
2080: 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20  [sqlite3_int64] 
2090: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
20a0: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
20b0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
20c0: 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nteger..**.** {H
20d0: 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  10202} The [sqli
20e0: 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b  te_uint64] and [
20f0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d 20  sqlite3_uint64] 
2100: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
2110: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
2120: 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
2130: 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66   integer..*/.#if
2140: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2150: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
2160: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2170: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
2180: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2190: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
21a0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
21b0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
21c0: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
21d0: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
21e0: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
21f0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2200: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2210: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2220: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2230: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2240: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2250: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2260: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
2270: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2280: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
2290: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
22a0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
22b0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
22c0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
22d0: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
22e0: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
22f0: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2300: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2310: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2320: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2330: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2340: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2350: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
2360: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
2370: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
2380: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
2390: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
23a0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
23b0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
23c0: 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c  ction {H12010} <
23d0: 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a  S30100><S40200>.
23e0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
23f0: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2400: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2410: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2420: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
2430: 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65  s should [sqlite
2440: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2450: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2460: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2470: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2480: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2490: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
24a0: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
24b0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
24c0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
24d0: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
24e0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
24f0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20   object..** The 
2500: 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2510: 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  mt()] interface 
2520: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
2530: 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72  ocate all.** [pr
2540: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2550: 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  s] associated wi
2560: 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
2570: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64 65  onnection] if de
2580: 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61  sired..** Typica
2590: 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f  l code might loo
25a0: 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  k like this:.**.
25b0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
25c0: 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  pre>.** sqlite3_
25d0: 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20  stmt *pStmt;.** 
25e0: 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d 20  while( (pStmt = 
25f0: 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2600: 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a  t(db, 0))!=0 ){.
2610: 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c 69  ** &nbsp;   sqli
2620: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74  te3_finalize(pSt
2630: 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70  mt);.** }.** </p
2640: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
2650: 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  .**.** If [sqlit
2660: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69  e3_close()] is i
2670: 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74  nvoked while a t
2680: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
2690: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
26a0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
26b0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
26c0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ack..**.** INVAR
26d0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
26e0: 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 73 66  2011} A successf
26f0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2700: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68  te3_close(C)] sh
2710: 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 65 0a  all destroy the.
2720: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
2730: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2740: 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a  ] object C..**.*
2750: 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73 75 63  * {H12012} A suc
2760: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2770: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2780: 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  )] shall return 
2790: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a  SQLITE_OK..**.**
27a0: 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75 63 63   {H12013} A succ
27b0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
27c0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
27d0: 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 65 20  ] shall release 
27e0: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
27f0: 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 74 65  memory and syste
2800: 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f  m resources asso
2810: 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 61 74  ciated with [dat
2820: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2830: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e  ].**          C.
2840: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 7d 20  .**.** {H12014} 
2850: 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
2860: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20  e3_close(C)] on 
2870: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
2880: 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a  ection] C that.*
2890: 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 20 6f  *          has o
28a0: 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20  ne or more open 
28b0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28c0: 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c  ents] shall fail
28d0: 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
28e0: 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53    an [SQLITE_BUS
28f0: 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a  Y] error code..*
2900: 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 41 20  *.** {H12015} A 
2910: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2920: 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72 65  _close(C)] where
2930: 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   C is a NULL poi
2940: 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  nter shall.**   
2950: 20 20 20 20 20 20 20 62 65 20 61 20 68 61 72 6d         be a harm
2960: 6c 65 73 73 20 6e 6f 2d 6f 70 20 72 65 74 75 72  less no-op retur
2970: 6e 69 6e 67 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  ning SQLITE_OK..
2980: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 39 7d 20 57  **.** {H12019} W
2990: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  hen [sqlite3_clo
29a0: 73 65 28 43 29 5d 20 69 73 20 69 6e 76 6f 6b 65  se(C)] is invoke
29b0: 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65  d on a [database
29c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 0a 2a   connection] C.*
29d0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
29e0: 68 61 73 20 61 20 70 65 6e 64 69 6e 67 20 74 72  has a pending tr
29f0: 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 20 74  ansaction, the t
2a00: 72 61 6e 73 61 63 74 69 6f 6e 20 73 68 61 6c 6c  ransaction shall
2a10: 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   be.**          
2a20: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
2a30: 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
2a40: 2a 2a 0a 2a 2a 20 7b 41 31 32 30 31 36 7d 20 54  **.** {A12016} T
2a50: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74  he C parameter t
2a60: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
2a70: 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74  (C)] must be eit
2a80: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20  her a NULL.**   
2a90: 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 6f         pointer o
2aa0: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2ab0: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2ac0: 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  tained.**       
2ad0: 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33     from [sqlite3
2ae0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2af0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
2b00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2b10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2b20: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
2b30: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a  usly closed..*/.
2b40: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2b50: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2b60: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2b70: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2b80: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2b90: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2ba0: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2bb0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2bc0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2bd0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2be0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2bf0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2c00: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2c10: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2c20: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2c30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2c40: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2c50: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2c60: 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30  e {H12100} <S100
2c70: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
2c90: 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76  erface is a conv
2ca0: 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75  enient way of ru
2cb0: 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72  nning one or mor
2cc0: 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
2cd0: 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69  nts without havi
2ce0: 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f  ng to write a lo
2cf0: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68  t of C code.  Th
2d00: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a  e UTF-8 encoded.
2d10: 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
2d20: 73 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20  s are passed in 
2d30: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
2d40: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2d50: 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68  e3_exec()..** Th
2d60: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  e statements are
2d70: 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62   evaluated one b
2d80: 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68  y one until eith
2d90: 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a  er an error or.*
2da0: 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69  * an interrupt i
2db0: 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f  s encountered, o
2dc0: 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65  r until they are
2dd0: 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20   all done.  The 
2de0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  3rd parameter.**
2df0: 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20   is an optional 
2e00: 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73  callback that is
2e10: 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
2e20: 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e  r each row of an
2e30: 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c  y query.** resul
2e40: 74 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74  ts produced by t
2e50: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2e60: 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61  s.  The 5th para
2e70: 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72  meter tells wher
2e80: 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e  e.** to write an
2e90: 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73  y error messages
2ea0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f  ..**.** The erro
2eb0: 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64  r message passed
2ec0: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
2ed0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
2ee0: 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65  is held.** in me
2ef0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2f00: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2f10: 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64  oc()].  To avoid
2f20: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a   a memory leak,.
2f30: 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61  ** the calling a
2f40: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
2f50: 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  d call [sqlite3_
2f60: 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65  free()] on any e
2f70: 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
2f80: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68  returned through
2f90: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
2fa0: 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  er when it has f
2fb0: 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a  inished using.**
2fc0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
2fd0: 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ge..**.** If the
2fe0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
2ff0: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  n the 2nd parame
3000: 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  ter is NULL or a
3010: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a  n empty string.*
3020: 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f  * or a string co
3030: 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68  ntaining only wh
3040: 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d  itespace and com
3050: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53  ments, then no S
3060: 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  QL.** statements
3070: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
3080: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  nd the database 
3090: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a  is not changed..
30a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
30b0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
30c0: 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
30d0: 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a  d in terms of.**
30e0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30f0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3100: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
3110: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3120: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ()]..** The sqli
3130: 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69  te3_exec() routi
3140: 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20  ne does nothing 
3150: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
3160: 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64  that cannot be d
3170: 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  one.** by [sqlit
3180: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
3190: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
31a0: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
31b0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
31c0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
31d0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 31 7d 20 41  **.** {H12101} A
31e0: 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
31f0: 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
3200: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
3210: 45 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E)].**          
3220: 73 68 61 6c 6c 20 73 65 71 75 65 6e 74 69 61 6c  shall sequential
3230: 6c 79 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20  ly evaluate all 
3240: 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  of the UTF-8 enc
3250: 6f 64 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  oded,.**        
3260: 20 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61    semicolon-sepa
3270: 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
3280: 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
3290: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
32a0: 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 53          string S
32b0: 20 77 69 74 68 69 6e 20 74 68 65 20 63 6f 6e 74   within the cont
32c0: 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ext of the [data
32d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32e0: 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30   D..**.** {H1210
32f0: 32 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  2} If the S para
3300: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3310: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3320: 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a  )] is NULL then.
3330: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
3340: 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 69  actions of the i
3350: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62  nterface shall b
3360: 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 69 66  e the same as if
3370: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
3380: 20 53 20 70 61 72 61 6d 65 74 65 72 20 77 65 72   S parameter wer
3390: 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  e an empty strin
33a0: 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 34  g..**.** {H12104
33b0: 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
33c0: 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  ue of [sqlite3_e
33d0: 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20  xec()] shall be 
33e0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61  [SQLITE_OK] if a
33f0: 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ll.**          S
3400: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75  QL statements ru
3410: 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61  n successfully a
3420: 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  nd to completion
3430: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 35 7d  ..**.** {H12105}
3440: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
3450: 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78  e of [sqlite3_ex
3460: 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 61  ec()] shall be a
3470: 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
3480: 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d 7a 65            non-ze
3490: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
34a0: 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61 74 65  if any SQL state
34b0: 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  ment fails..**.*
34c0: 2a 20 7b 48 31 32 31 30 37 7d 20 49 66 20 6f 6e  * {H12107} If on
34d0: 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
34e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
34f0: 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74  handed to [sqlit
3500: 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20  e3_exec()].**   
3510: 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 72 65         return re
3520: 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20 33 72  sults and the 3r
3530: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
3540: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a  ot NULL, then.**
3550: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61            the ca
3560: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3570: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
3580: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 73   3rd parameter s
3590: 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20  hall be.**      
35a0: 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65      invoked once
35b0: 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66   for each row of
35c0: 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b   result..**.** {
35d0: 48 31 32 31 31 30 7d 20 49 66 20 74 68 65 20 63  H12110} If the c
35e0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
35f0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65  a non-zero value
3600: 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65   then [sqlite3_e
3610: 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  xec()].**       
3620: 20 20 20 73 68 61 6c 6c 20 61 62 6f 72 74 20 74     shall abort t
3630: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3640: 20 69 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79   it is currently
3650: 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20   evaluating,.** 
3660: 20 20 20 20 20 20 20 20 20 73 6b 69 70 20 61 6c           skip al
3670: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  l subsequent SQL
3680: 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64   statements, and
3690: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
36a0: 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ABORT]..**.** {H
36b0: 31 32 31 31 33 7d 20 54 68 65 20 5b 73 71 6c 69  12113} The [sqli
36c0: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74  te3_exec()] rout
36d0: 69 6e 65 20 73 68 61 6c 6c 20 70 61 73 73 20 69  ine shall pass i
36e0: 74 73 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  ts 4th parameter
36f0: 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20 20 20   through.**     
3700: 20 20 20 20 20 61 73 20 74 68 65 20 31 73 74 20       as the 1st 
3710: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
3720: 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
3730: 20 7b 48 31 32 31 31 36 7d 20 54 68 65 20 5b 73   {H12116} The [s
3740: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
3750: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74  outine shall set
3760: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3770: 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20  er of its.**    
3780: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74        callback t
3790: 6f 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  o be the number 
37a0: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
37b0: 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
37c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
37d0: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ult..**.** {H121
37e0: 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
37f0: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65  _exec()] routine
3800: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 33   shall set the 3
3810: 72 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  rd parameter of 
3820: 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
3830: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61  callback to be a
3840: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3850: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68  ers to strings h
3860: 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  olding the.**   
3870: 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 66 6f         values fo
3880: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e  r each column in
3890: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73   the current res
38a0: 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73 0a 2a  ult set row as.*
38b0: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69  *          obtai
38c0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
38d0: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
38e0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 32 7d  ..**.** {H12122}
38f0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
3900: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  ec()] routine sh
3910: 61 6c 6c 20 73 65 74 20 74 68 65 20 34 74 68 20  all set the 4th 
3920: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73  parameter of its
3930: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
3940: 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61  lback to be an a
3950: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3960: 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64   to strings hold
3970: 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ing the.**      
3980: 20 20 20 20 6e 61 6d 65 73 20 6f 66 20 72 65 73      names of res
3990: 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f  ult columns as o
39a0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
39b0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
39c0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  e()]..**.** {H12
39d0: 31 32 35 7d 20 49 66 20 74 68 65 20 33 72 64 20  125} If the 3rd 
39e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
39f0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
3a00: 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20   NULL then.**   
3a10: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
3a20: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 69  exec()] shall si
3a30: 6c 65 6e 74 6c 79 20 64 69 73 63 61 72 64 20 71  lently discard q
3a40: 75 65 72 79 20 72 65 73 75 6c 74 73 2e 0a 2a 2a  uery results..**
3a50: 0a 2a 2a 20 7b 48 31 32 31 33 31 7d 20 49 66 20  .** {H12131} If 
3a60: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
3a70: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72  while parsing or
3a80: 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20   evaluating any 
3a90: 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20  of the SQL.**   
3aa0: 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
3ab0: 73 20 69 6e 20 74 68 65 20 53 20 70 61 72 61 6d  s in the S param
3ac0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
3ad0: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3ae0: 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20  ] and if.**     
3af0: 20 20 20 20 20 74 68 65 20 45 20 70 61 72 61 6d       the E param
3b00: 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  eter is not NULL
3b10: 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  , then [sqlite3_
3b20: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 74  exec()] shall st
3b30: 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
3b40: 69 6e 20 2a 45 20 61 6e 20 61 70 70 72 6f 70 72  in *E an appropr
3b50: 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
3b60: 67 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ge written into 
3b70: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a  memory obtained.
3b80: 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
3b90: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
3ba0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ()]..**.** {H121
3bb0: 33 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  34} The [sqlite3
3bc0: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3bd0: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
3be0: 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66  set the value of
3bf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 45 20  .**          *E 
3c00: 74 6f 20 4e 55 4c 4c 20 69 66 20 45 20 69 73 20  to NULL if E is 
3c10: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65  not NULL and the
3c20: 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73  re are no errors
3c30: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 37 7d  ..**.** {H12137}
3c40: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
3c50: 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66  ec(D,S,C,A,E)] f
3c60: 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65  unction shall se
3c70: 74 20 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64  t the [error cod
3c80: 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  e].**          a
3c90: 6e 64 20 6d 65 73 73 61 67 65 20 61 63 63 65 73  nd message acces
3ca0: 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74  sible via [sqlit
3cb0: 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 0a  e3_errcode()], .
3cc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3cd0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
3ce0: 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20  rcode()],.**    
3cf0: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
3d00: 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73  rrmsg()], and [s
3d10: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
3d20: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33  )]..**.** {H1213
3d30: 38 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  8} If the S para
3d40: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3d50: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3d60: 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  )] is NULL or an
3d70: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6d 70  .**          emp
3d80: 74 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e  ty string or con
3d90: 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74  tains nothing ot
3da0: 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70  her than whitesp
3db0: 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a  ace, comments,.*
3dc0: 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 2f 6f  *          and/o
3dd0: 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68  r semicolons, th
3de0: 65 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73  en results of [s
3df0: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
3e00: 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
3e10: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
3e20: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
3e30: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3e40: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
3e50: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3e60: 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
3e70: 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 74 6f    shall reset to
3e80: 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72 72   indicate no err
3e90: 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ors..**.** ASSUM
3ea0: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
3eb0: 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73 74  12141} The first
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
3ed0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6d  qlite3_exec()] m
3ee0: 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 20  ust be an valid 
3ef0: 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 20  and open.**     
3f00: 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
3f10: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
3f20: 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 20 64  * {A12142} The d
3f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3f40: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63  on must not be c
3f50: 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 20  losed while.**  
3f60: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
3f70: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
3f80: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31  ing..**.** {A121
3f90: 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  43} The calling 
3fa0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
3fb0: 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  use [sqlite3_fre
3fc0: 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20  e()] to free.** 
3fd0: 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d           the mem
3fe0: 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67  ory that *errmsg
3ff0: 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
4000: 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72  g at once the er
4010: 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ror.**          
4020: 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c 6f  message is no lo
4030: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a  nger needed..**.
4040: 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 65 20  ** {A12145} The 
4050: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
4060: 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61  xt in the 2nd pa
4070: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
4080: 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20  te3_exec()].**  
4090: 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 65 6d          must rem
40a0: 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77 68  ain unchanged wh
40b0: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ile [sqlite3_exe
40c0: 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  c()] is running.
40d0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
40e0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
40f0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4120: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4130: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4150: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4160: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4170: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4180: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4190: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
41a0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
41b0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
41c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
41f0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4200: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4210: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4230: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4240: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4250: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4260: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31  Result Codes {H1
4270: 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  0210} <S10700>.*
4280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4290: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
42a0: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
42b0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
42c0: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
42d0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
42e0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
42f0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
4300: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
4310: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
4320: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
4330: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4340: 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72  cates success or
4350: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
4360: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
4370: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
4380: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
4390: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
43a0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
43b0: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
43c0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
43d0: 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  codes].*/.#defin
43e0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
43f0: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4400: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4410: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4420: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4440: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4450: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
4460: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
4470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4480: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
4490: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
44a0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
44b0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
44c0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
44d0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
44e0: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
44f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4500: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4510: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4520: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4530: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4550: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4560: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4570: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
4580: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4590: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
45a0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
45b0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
45c0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
45d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
45e0: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
45f0: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4600: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4610: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4620: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4630: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4640: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4660: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4670: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
4680: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
4690: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
46a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46b0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
46c0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
46d0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
46e0: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
46f0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4700: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4710: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4720: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4730: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4740: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4750: 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53    12   /* NOT US
4760: 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63  ED. Table or rec
4770: 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f  ord not found */
4780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4790: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
47a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
47b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
47c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
47d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
47f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4800: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4810: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4820: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
4830: 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55     15   /* NOT U
4840: 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f  SED. Database lo
4850: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f  ck protocol erro
4860: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4870: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20  ITE_EMPTY       
4880: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  16   /* Database
4890: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65   is empty */.#de
48a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45  fine SQLITE_SCHE
48b0: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20  MA      17   /* 
48c0: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  The database sch
48d0: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23  ema changed */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f  define SQLITE_TO
48f0: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f  OBIG      18   /
4900: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  * String or BLOB
4910: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69   exceeds size li
4920: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mit */.#define S
4930: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
4940: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20    19   /* Abort 
4950: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e  due to constrain
4960: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23  t violation */.#
4970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4980: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f  SMATCH    20   /
4990: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d  * Data type mism
49a0: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20  atch */.#define 
49b0: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20  SQLITE_MISUSE   
49c0: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61     21   /* Libra
49d0: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63  ry used incorrec
49e0: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tly */.#define S
49f0: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20  QLITE_NOLFS     
4a00: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f    22   /* Uses O
4a10: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73  S features not s
4a20: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74  upported on host
4a30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a40: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32  TE_AUTH        2
4a50: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61  3   /* Authoriza
4a60: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  tion denied */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f  define SQLITE_FO
4a80: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f  RMAT      24   /
4a90: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61  * Auxiliary data
4aa0: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f  base format erro
4ab0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4ac0: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20  ITE_RANGE       
4ad0: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61  25   /* 2nd para
4ae0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4af0: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e  _bind out of ran
4b00: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge */.#define SQ
4b10: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20  LITE_NOTADB     
4b20: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70   26   /* File op
4b30: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74  ened that is not
4b40: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
4b50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b60: 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31  TE_ROW         1
4b70: 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  00  /* sqlite3_s
4b80: 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65  tep() has anothe
4b90: 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23  r row ready */.#
4ba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f  define SQLITE_DO
4bb0: 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f  NE        101  /
4bc0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
4bd0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
4be0: 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e  ecuting */./* en
4bf0: 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  d-of-error-codes
4c00: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
4c10: 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65  REF: Extended Re
4c20: 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30 32  sult Codes {H102
4c30: 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20  20} <S10700>.** 
4c40: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c50: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4c60: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4c70: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4c80: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c90: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4ca0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4cb0: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4cc0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4cd0: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4ce0: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4cf0: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4d00: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4d10: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4d20: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4d30: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4d40: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4d50: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4d60: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4d70: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4d80: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d90: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4da0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4db0: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4dc0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4dd0: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4de0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4df0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4e00: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4e10: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4e20: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4e30: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4e40: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4e50: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4e60: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4e70: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4e80: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e90: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4ea0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4eb0: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4ec0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4ed0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4ee0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4ef0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4f00: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4f10: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4f20: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4f30: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4f40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f50: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4f60: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4f70: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4f80: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f90: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4fa0: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4fb0: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4fc0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4fd0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4fe0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4ff0: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
5000: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
5010: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
5020: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
5030: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
5040: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
5050: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
5060: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
5070: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a  exactly zero..**
5080: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
5090: 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d 20 54  **.** {H10223} T
50a0: 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
50b0: 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64   for an extended
50c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68 61   result code sha
50d0: 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  ll contains.**  
50e0: 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74 65          a relate
50f0: 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74  d primary result
5100: 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 69   code as a prefi
5110: 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 34  x..**.** {H10224
5120: 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74  } Primary result
5130: 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c   code names shal
5140: 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67  l contain a sing
5150: 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72  le "_" character
5160: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 35 7d  ..**.** {H10225}
5170: 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   Extended result
5180: 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c   code names shal
5190: 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72  l contain two or
51a0: 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63   more "_" charac
51b0: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ters..**.** {H10
51c0: 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 63  226} The numeric
51d0: 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 74   value of an ext
51e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
51f0: 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20  e shall contain 
5200: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
5210: 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66  numeric value of
5220: 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64 69   its correspondi
5230: 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c  ng primary resul
5240: 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20 20  t code in.**    
5250: 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74 20        its least 
5260: 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62 69  significant 8 bi
5270: 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ts..*/.#define S
5280: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
5290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
52a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
52b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
52d0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
52e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
52f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5300: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
5310: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5320: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
5330: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5340: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
5350: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5360: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
5390: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
53b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53c0: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
53d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
53e0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
53f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5400: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
5410: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5420: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
5430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5440: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5450: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5460: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5480: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5490: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54a0: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
54b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54c0: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
54d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
54e0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
54f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5500: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
5510: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5520: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5540: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5560: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5580: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5590: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55a0: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
55b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55c0: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
55d0: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
55e0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
55f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5600: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
5610: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5620: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 0a 2f  RR | (15<<8))../
5630: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
5640: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
5650: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48  en Operations {H
5660: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20  10230} <H11120> 
5670: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12700>.**.** T
5680: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
5690: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
56a0: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
56b0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
56c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
56d0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
56e0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
56f0: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
5700: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
5710: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
5720: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
5730: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5740: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
5750: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
5760: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
5770: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
5780: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
5790: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
57a0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
57b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
57c0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
57d0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
57e0: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
57f0: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
5800: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
5810: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
5820: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
5830: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
5840: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5850: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
5860: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
5870: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5880: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
5890: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
58a0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
58b0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
58c0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
58d0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
58e0: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
58f0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
5900: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5910: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
5920: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
5930: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
5940: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  2000.#define SQL
5950: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
5960: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
5970: 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  4000.#define SQL
5980: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
5990: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
59a0: 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  8000.#define SQL
59b0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
59c0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
59d0: 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0000../*.** CAPI
59e0: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
59f0: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
5a00: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
5a10: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5a20: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
5a30: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
5a40: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
5a50: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
5a60: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
5a70: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5a80: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5a90: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5aa0: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5ab0: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5ac0: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5ad0: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5ae0: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5af0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5b00: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5b10: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
5b20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5b30: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
5b40: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
5b50: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
5b60: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
5b70: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5b80: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5b90: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5ba0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5bb0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5bc0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5bd0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5be0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5bf0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5c00: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5c10: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
5c20: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5c30: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
5c40: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
5c50: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
5c60: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
5c70: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5c80: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5c90: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5ca0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5cb0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5cc0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5cd0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5ce0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5cf0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5d00: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5d10: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
5d20: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
5d30: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
5d40: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
5d50: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
5d60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5d70: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
5d80: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5d90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5da0: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
5db0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
5dc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5dd0: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
5de0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
5df0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e00: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
5e10: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
5e20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e30: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
5e40: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5e50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e60: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
5e70: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
5e80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e90: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
5ea0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
5eb0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ec0: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
5ed0: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
5ee0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ef0: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
5f00: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
5f10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5f20: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
5f30: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
5f40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
5f50: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
5f60: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
5f70: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
5f80: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
5f90: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
5fa0: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
5fb0: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
5fc0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
5fd0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
5fe0: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
5ff0: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
6000: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
6010: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
6020: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
6030: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6040: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
6050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6060: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
6070: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
6080: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
6090: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
60a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
60b0: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
60c0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
60d0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
60e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
60f0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
6100: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
6110: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
6120: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
6130: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
6140: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
6150: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
6160: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
6170: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6180: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6190: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
61a0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
61b0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
61c0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
61d0: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
61e0: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
61f0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6200: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
6210: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
6220: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
6230: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
6240: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
6250: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
6260: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
6270: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
6280: 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54  ushed. The SQLIT
6290: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c  E_SYNC_NORMAL fl
62a0: 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  ag means.** to u
62b0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
62c0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65  ) semantics. The
62d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
62e0: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20  L flag means.** 
62f0: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58 20  to use Mac OS-X 
6300: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
6310: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
6320: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
6330: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6340: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
6350: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6360: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
6370: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
6380: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6390: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
63a0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
63b0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
63c0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
63d0: 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30  le {H11110} <S20
63e0: 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  110>.**.** An [s
63f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6400: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
6410: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
6420: 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61  he OS.** interfa
6430: 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76  ce layer.  Indiv
6440: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
6450: 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ce implementatio
6460: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
6470: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
6480: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
6490: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
64a0: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
64b0: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
64c0: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
64d0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
64e0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
64f0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6500: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
6510: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
6520: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
6530: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
6540: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
6550: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
6560: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
6570: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
6580: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
6590: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
65a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
65b0: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
65c0: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
65d0: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
65e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
65f0: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
6600: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
6610: 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30 7d   Object {H11120}
6620: 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S20110>.**.** 
6630: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
6640: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
6650: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74  3_vfs] xOpen met
6660: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
6670: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
6680: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
6690: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
66a0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
66b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
66c0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
66d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
66e0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
66f0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
6700: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
6710: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
6720: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
6730: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
6740: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
6750: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
6760: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
6770: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
6780: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
6790: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
67a0: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
67b0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
67c0: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
67d0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
67e0: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
67f0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
6800: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
6810: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
6820: 20 61 20 4d 61 63 20 4f 53 2d 58 20 73 74 79 6c   a Mac OS-X styl
6830: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
6840: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
6850: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
6860: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
6870: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
6880: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
6890: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
68a0: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
68b0: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
68c0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
68d0: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
68e0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
68f0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
6900: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6910: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
6920: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
6930: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
6940: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
6950: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
6960: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
6970: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
6980: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
6990: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
69a0: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
69b0: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
69c0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
69d0: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
69e0: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
69f0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
6a00: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
6a10: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
6a20: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
6a30: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
6a40: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
6a50: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
6a60: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
6a70: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
6a80: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
6a90: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
6aa0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
6ab0: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
6ac0: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
6ad0: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
6ae0: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
6af0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
6b00: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
6b10: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
6b20: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
6b30: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
6b40: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
6b50: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
6b60: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
6b70: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
6b80: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
6b90: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
6ba0: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
6bb0: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
6bc0: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
6bd0: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
6be0: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
6bf0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
6c00: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
6c10: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
6c20: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
6c30: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
6c40: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
6c50: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
6c60: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
6c70: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
6c80: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
6c90: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
6ca0: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
6cb0: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
6cc0: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
6cd0: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
6ce0: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
6cf0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
6d00: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
6d10: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
6d20: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
6d30: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
6d40: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
6d50: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
6d60: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
6d70: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
6d80: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
6d90: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
6da0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
6db0: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
6dc0: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
6dd0: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
6de0: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
6df0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
6e00: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
6e10: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
6e20: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
6e30: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
6e40: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
6e50: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nflicts..**.** T
6e60: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
6e70: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6e80: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
6e90: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
6ea0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
6eb0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
6ec0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
6ed0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
6ee0: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
6ef0: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
6f00: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
6f10: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
6f20: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
6f30: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6f40: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
6f50: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
6f60: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
6f70: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
6f80: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
6f90: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
6fa0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
6fb0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
6fc0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6fd0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
6fe0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6ff0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
7000: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7010: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
7020: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7030: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
7040: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7050: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
7060: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7070: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
7080: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7090: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
70a0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
70b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
70c0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
70d0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
70e0: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
70f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
7100: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
7110: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
7120: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
7130: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
7140: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
7150: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
7160: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
7170: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7180: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
7190: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
71a0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
71b0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
71c0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
71d0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
71e0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
71f0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
7200: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
7210: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
7220: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
7230: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
7240: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
7250: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
7260: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
7270: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
7280: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
7290: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
72a0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
72b0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
72c0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
72d0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
72e0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
72f0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
7300: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
7310: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
7320: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
7330: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
7340: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
7350: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
7360: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
7370: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
7380: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
7390: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
73a0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
73b0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
73c0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
73d0: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
73e0: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
73f0: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
7400: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
7410: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
7420: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
7430: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
7440: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
7450: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
7460: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
7470: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7480: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
7490: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
74a0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
74b0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
74c0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
74d0: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
74e0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
74f0: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
7500: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
7510: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7520: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7530: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
7540: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
7550: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
7560: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
7570: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
7580: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
7590: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
75a0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
75b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
75c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
75d0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
75e0: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
75f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
7600: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
7610: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
7620: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
7630: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
7640: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
7650: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
7660: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
7670: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
7680: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
7690: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
76a0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
76b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
76c0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
76d0: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
76e0: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
76f0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
7700: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
7710: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
7720: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64  _file*);.  /* Ad
7730: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
7740: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
7750: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
7760: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
7770: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
7780: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
7790: 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d 20 3c  codes {H11310} <
77a0: 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30800>.**.** Th
77b0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
77c0: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
77d0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
77e0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
77f0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
7800: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7810: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
7820: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7830: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
7840: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
7850: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
7860: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
7870: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
7880: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
7890: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
78a0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
78b0: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
78c0: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
78d0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
78e0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
78f0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
7900: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7910: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
7920: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
7930: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
7940: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
7950: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
7960: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
7970: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
7980: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
7990: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
79a0: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
79b0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
79c0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
79d0: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
79e0: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
79f0: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
7a00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7a10: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
7a20: 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a          1../*.**
7a30: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
7a40: 20 48 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d   Handle {H17110}
7a50: 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20   <S20130>.**.** 
7a60: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
7a70: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
7a80: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
7a90: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
7aa0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
7ab0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
7ac0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
7ad0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
7ae0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
7af0: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
7b00: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
7b10: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
7b20: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
7b30: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
7b40: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
7b50: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7b60: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
7b70: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
7b80: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
7b90: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
7ba0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
7bb0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
7bc0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7bd0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7be0: 4f 62 6a 65 63 74 20 7b 48 31 31 31 34 30 7d 20  Object {H11140} 
7bf0: 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S20100>.**.** A
7c00: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
7c10: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
7c20: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
7c30: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
7c40: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
7c50: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
7c60: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
7c70: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
7c80: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
7c90: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
7ca0: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
7cb0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
7cc0: 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  em"..**.** The v
7cd0: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
7ce0: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
7cf0: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
7d00: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
7d10: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
7d20: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
7d30: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
7d40: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
7d50: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
7d60: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
7d70: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
7d80: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
7d90: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
7da0: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
7db0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
7dc0: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
7dd0: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
7de0: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
7df0: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
7e00: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
7e10: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
7e20: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
7e30: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
7e40: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
7e50: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
7e60: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
7e70: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
7e80: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
7e90: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
7ea0: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
7eb0: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
7ec0: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
7ed0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
7ee0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
7ef0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
7f00: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
7f10: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
7f20: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
7f30: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
7f40: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
7f50: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
7f60: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
7f70: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
7f80: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
7f90: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
7fa0: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
7fb0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
7fc0: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
7fd0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
7fe0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
7ff0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
8000: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
8010: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
8020: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
8030: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
8040: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
8050: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
8060: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
8070: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
8080: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
8090: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
80a0: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
80b0: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
80c0: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
80d0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
80e0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
80f0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
8100: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
8110: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
8120: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
8130: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
8140: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
8150: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
8160: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
8170: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
8180: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
8190: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
81a0: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
81b0: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
81c0: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
81d0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
81e0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 31 7d  ..**.** {H11141}
81f0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61   SQLite will gua
8200: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20  rantee that the 
8210: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
8220: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
8230: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
8240: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
8250: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
8260: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
8270: 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72  e().  SQLite fur
8280: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
8290: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
82a0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
82b0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
82c0: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
82d0: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 7b 45 4e 44  .** called. {END
82e0: 7d 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  }  Because of th
82f0: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
8300: 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nse,.** the [sql
8310: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
8320: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
8330: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
8340: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
8350: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
8360: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
8370: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
8380: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
8390: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
83a0: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
83b0: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
83c0: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69 74  en.** must invit
83d0: 65 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  e its own tempor
83e0: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
83f0: 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72   file.  Whenever
8400: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
8410: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
8420: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
8430: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
8440: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
8450: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will 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 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8480: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34  E]..**.** {H1114
8490: 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  2} The flags arg
84a0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
84b0: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
84c0: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
84d0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
84e0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
84f0: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
8500: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
8510: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
8520: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
8530: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
8540: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
8550: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
8560: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
8570: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
8580: 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f  . {END}.** If xO
8590: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
85a0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
85b0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
85c0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
85d0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
85e0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
85f0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
8600: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
8610: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 33 7d 20  .**.** {H11143} 
8620: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
8630: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
8640: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
8650: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
8660: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
8670: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
8680: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
8690: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
86a0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
86b0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
86c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
86d0: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
86e0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
86f0: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
8700: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8710: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
8720: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8730: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
8740: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
8750: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
8760: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
8770: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
8780: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f  R_JOURNAL].** </
8790: 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ul> {END}.**.** 
87a0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
87b0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
87c0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
87d0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
87e0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
87f0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
8800: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
8810: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
8820: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
8830: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
8840: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
8850: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
8860: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
8870: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
8880: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
8890: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
88a0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
88b0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
88c0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
88d0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
88e0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
88f0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
8900: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
8910: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
8920: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
8930: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
8940: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
8950: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
8960: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
8970: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
8980: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
8990: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
89a0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
89b0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
89c0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
89d0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
89e0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
89f0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
8a00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
8a10: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8a20: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
8a30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
8a40: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
8a50: 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 35 7d  >.**.** {H11145}
8a60: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
8a70: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8a80: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
8a90: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
8aa0: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
8ab0: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 48  t is closed.  {H
8ac0: 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49  11146} The [SQLI
8ad0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8ae0: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
8af0: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20  e set for TEMP  
8b00: 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e  databases, journ
8b10: 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a  als and for subj
8b20: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ournals..**.** {
8b30: 48 31 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c  H11147} The [SQL
8b40: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8b50: 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  VE] flag means t
8b60: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
8b70: 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20  e opened.** for 
8b80: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8b90: 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 73 20  .  This flag is 
8ba0: 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65  set for all file
8bb0: 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20  s except.** for 
8bc0: 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
8bd0: 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e file..**.** {H
8be0: 31 31 31 34 38 7d 20 41 74 20 6c 65 61 73 74 20  11148} At least 
8bf0: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
8c00: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
8c10: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
8c20: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
8c30: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
8c40: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
8c50: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
8c60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
8c70: 65 6e 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 78  en. {END}  The x
8c80: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
8c90: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
8ca0: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
8cb0: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
8cc0: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
8cd0: 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 39  n..**.** {H11149
8ce0: 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  } The flags argu
8cf0: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
8d00: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
8d10: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
8d20: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
8d30: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
8d40: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
8d50: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
8d60: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
8d70: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
8d80: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
8d90: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
8da0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
8db0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
8dc0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
8dd0: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
8de0: 20 7b 45 4e 44 7d 20 20 54 68 65 20 66 69 6c 65   {END}  The file
8df0: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
8e00: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ectory..**.** {H
8e10: 31 31 31 35 30 7d 20 53 51 4c 69 74 65 20 77 69  11150} SQLite wi
8e20: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
8e30: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
8e40: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
8e50: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
8e60: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
8e70: 68 6e 61 6d 65 2e 20 7b 48 31 31 31 35 31 7d 20  hname. {H11151} 
8e80: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
8e90: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
8ea0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
8eb0: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
8ec0: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
8ed0: 74 68 6f 64 73 2e 20 7b 45 4e 44 7d 20 20 49 66  thods. {END}  If
8ee0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
8ef0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
8f00: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
8f10: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
8f20: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
8f30: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
8f40: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
8f50: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
8f60: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
8f70: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
8f80: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
8f90: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
8fa0: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
8fb0: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
8fc0: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
8fd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
8fe0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
8ff0: 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  p(), and xCurren
9000: 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63  tTime() interfac
9010: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74  es.** are not st
9020: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
9030: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
9040: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
9050: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
9060: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
9070: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
9080: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
9090: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
90a0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
90b0: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
90c0: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
90d0: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
90e0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
90f0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
9100: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
9110: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
9120: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
9130: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
9140: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
9150: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
9160: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
9170: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
9180: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
9190: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
91a0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
91b0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
91c0: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
91d0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
91e0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
91f0: 64 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64  d time..*/.typed
9200: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
9210: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
9220: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
9230: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
9240: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
9250: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
9260: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a  version number *
9270: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
9280: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
9290: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
92a0: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
92b0: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
92c0: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
92d0: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
92e0: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
92f0: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
9300: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
9310: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
9320: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
9330: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
9340: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
9350: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
9360: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
9370: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
9380: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
9390: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
93a0: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
93b0: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
93c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
93d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
93e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
93f0: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
9400: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
9410: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
9420: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
9430: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
9440: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
9450: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
9460: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
9470: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
9480: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
9490: 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  ags, int *pResOu
94a0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
94b0: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
94c0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
94d0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
94e0: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
94f0: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
9500: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
9510: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9520: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
9530: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
9540: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
9550: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
9560: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a  rrMsg);.  void *
9570: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
9580: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
9590: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
95a0: 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  l);.  void (*xDl
95b0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
95c0: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
95d0: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
95e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
95f0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
9600: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
9610: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
9620: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
9630: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
9640: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
9650: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
9660: 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ble*);.  int (*x
9670: 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
9680: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
9690: 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e   char *);.  /* N
96a0: 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
96b0: 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67   appended in fig
96c0: 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
96d0: 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
96e0: 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
96f0: 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
9700: 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a  his happens. */.
9710: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
9720: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
9730: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
9740: 74 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48  thod {H11190} <H
9750: 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31  11140>.**.** {H1
9760: 31 31 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65  1191} These inte
9770: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
9780: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
9790: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
97a0: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
97b0: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
97c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
97d0: 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65  ject. {END}  The
97e0: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
97f0: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
9800: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
9810: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
9820: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 7b 48  oking for..** {H
9830: 31 31 31 39 32 7d 20 57 69 74 68 20 53 51 4c 49  11192} With SQLI
9840: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
9850: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
9860: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
9870: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
9880: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
9890: 2a 20 7b 48 31 31 31 39 33 7d 20 57 69 74 68 20  * {H11193} With 
98a0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
98b0: 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
98c0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
98d0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
98e0: 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72  e file is both r
98f0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
9900: 61 62 6c 65 2e 0a 2a 2a 20 7b 48 31 31 31 39 34  able..** {H11194
9910: 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  } With SQLITE_AC
9920: 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
9930: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
9940: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
9950: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
9960: 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  able..*/.#define
9970: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
9980: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
9990: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
99a0: 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65  _READWRITE 1.#de
99b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
99c0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a  SS_READ      2..
99d0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
99e0: 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53  Initialize The S
99f0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48  QLite Library {H
9a00: 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30 3e 3c  10130} <S20000><
9a10: 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30100>.**.** Th
9a20: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9a30: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
9a40: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
9a50: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
9a60: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
9a70: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
9a80: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
9a90: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
9aa0: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
9ab0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
9ac0: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a  itialize()..**.*
9ad0: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
9ae0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9af0: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
9b00: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
9b10: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69  .** the first ti
9b20: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
9b30: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
9b40: 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ed during the li
9b50: 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65  fetime of.** the
9b60: 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
9b70: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  it is the first 
9b80: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
9b90: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
9ba0: 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  oked.** followin
9bb0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  g a call to sqli
9bc0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
9bd0: 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69   Only an effecti
9be0: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
9bf0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9c00: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
9c10: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
9c20: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
9c30: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
9c40: 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  ops..**.** Among
9c50: 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73   other things, s
9c60: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9c70: 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65  e() shall invoke
9c80: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
9c90: 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c  nit().  Similarl
9ca0: 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y, sqlite3_shutd
9cb0: 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69  own().** shall i
9cc0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73  nvoke sqlite3_os
9cd0: 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  _end()..**.** Th
9ce0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9cf0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
9d00: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
9d10: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
9d20: 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65  * If for some re
9d30: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
9d40: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
9d50: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
9d60: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
9d70: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
9d80: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
9d90: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
9da0: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
9db0: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
9dc0: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
9dd0: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
9de0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
9df0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
9e00: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
9e10: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
9e20: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
9e30: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
9e40: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
9e50: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
9e60: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
9e70: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
9e80: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
9e90: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
9ea0: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
9eb0: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
9ec0: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
9ed0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9ee0: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
9ef0: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
9f00: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
9f10: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
9f20: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
9f30: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
9f40: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
9f50: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
9f60: 65 61 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20  eady.  However, 
9f70: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
9f80: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
9f90: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
9fa0: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
9fb0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
9fc0: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
9fd0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
9fe0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
9ff0: 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
a000: 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
a010: 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
a020: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a030: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
a040: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
a050: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
a060: 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
a070: 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
a080: 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
a090: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
a0a0: 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
a0b0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
a0c0: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
a0d0: 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
a0e0: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
a0f0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
a100: 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
a110: 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
a120: 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
a130: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
a140: 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
a150: 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
a160: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
a170: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
a180: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
a190: 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
a1a0: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
a1b0: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
a1c0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
a1d0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
a1e0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
a1f0: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
a200: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
a210: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
a220: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
a230: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
a240: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
a250: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
a260: 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
a270: 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
a280: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
a290: 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
a2a0: 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
a2b0: 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
a2c0: 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
a2d0: 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
a2e0: 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
a2f0: 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
a300: 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
a310: 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
a320: 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
a330: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
a340: 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
a350: 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
a360: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
a370: 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
a380: 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
a390: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
a3a0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
a3b0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
a3c0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
a3d0: 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
a3e0: 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
a3f0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
a400: 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
a410: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
a420: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
a430: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a440: 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
a450: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
a460: 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
a470: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
a480: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
a490: 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
a4a0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
a4b0: 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
a4c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
a4d0: 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
a4e0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
a4f0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
a500: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
a510: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
a520: 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
a530: 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
a540: 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75 6e 69  compiled for uni
a550: 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72 20 6f  x, windows, or o
a560: 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62 75 69  s/2..** When bui
a570: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
a580: 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20 74 68  tforms (using th
a590: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
a5a0: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
a5b0: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
a5c0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
a5d0: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
a5e0: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
a5f0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
a600: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
a610: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a620: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
a630: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
a640: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
a650: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a660: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
a670: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
a680: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
a690: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
a6a0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
a6b0: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
a6c0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
a6d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a6e0: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
a6f0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a700: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
a710: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
a720: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
a730: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
a740: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
a750: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
a760: 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 34  ite Library {H14
a770: 31 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33  100} <S20000><S3
a780: 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0200>.** EXPERIM
a790: 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ENTAL.**.** The 
a7a0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a7b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
a7c0: 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
a7d0: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
a7e0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
a7f0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
a800: 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
a810: 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
a820: 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
a830: 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
a840: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
a850: 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
a860: 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
a870: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
a880: 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
a890: 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
a8a0: 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
a8b0: 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
a8c0: 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
a8d0: 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
a8e0: 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
a8f0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
a900: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
a910: 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
a920: 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
a930: 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
a940: 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
a950: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
a960: 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
a970: 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
a980: 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
a990: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
a9a0: 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
a9b0: 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
a9c0: 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
a9d0: 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
a9e0: 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
a9f0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
aa00: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
aa10: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
aa20: 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
aa30: 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
aa40: 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f  utdown()]..** No
aa50: 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
aa60: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
aa70: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
aa80: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
aa90: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
aaa0: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
aab0: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
aac0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
aad0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
aae0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
aaf0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
ab00: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
ab10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
ab20: 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e  NGLETHREAD | con
ab30: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ab40: 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
ab50: 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
ab60: 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
ab70: 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
ab80: 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
ab90: 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
aba0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
abb0: 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
abc0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
abd0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
abe0: 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
abf0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
ac00: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e  **.** When a con
ac10: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ac20: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
ac30: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
ac40: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
ac50: 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  ** If the option
ac60: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
ac70: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
ac80: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
ac90: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
aca0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
acb0: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
acc0: 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e   code]..**.** IN
acd0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
ace0: 7b 48 31 34 31 30 33 7d 20 41 20 73 75 63 63 65  {H14103} A succe
acf0: 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
ad00: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   of [sqlite3_con
ad10: 66 69 67 28 29 5d 20 73 68 61 6c 6c 20 72 65 74  fig()] shall ret
ad20: 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
ad30: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
ad40: 2a 2a 20 7b 48 31 34 31 30 36 7d 20 54 68 65 20  ** {H14106} The 
ad50: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ad60: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
ad70: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
ad80: 45 5f 4d 49 53 55 53 45 5d 0a 2a 2a 20 20 20 20  E_MISUSE].**    
ad90: 20 20 20 20 20 20 69 66 20 69 74 20 69 73 20 69        if it is i
ada0: 6e 76 6f 6b 65 64 20 69 6e 20 62 65 74 77 65 65  nvoked in betwee
adb0: 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
adc0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
add0: 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
ade0: 20 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64    [sqlite3_shutd
adf0: 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  own()]..**.** {H
ae00: 31 34 31 32 30 7d 20 41 20 73 75 63 63 65 73 73  14120} A success
ae10: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
ae20: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
ae30: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
ae40: 4c 45 54 48 52 45 41 44 5d 29 0a 2a 2a 20 20 20  LETHREAD]).**   
ae50: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65 74         shall set
ae60: 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68   the default [th
ae70: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
ae80: 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 0a   Single-thread..
ae90: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 33 7d 20 41  **.** {H14123} A
aea0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
aeb0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
aec0: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
aed0: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
aee0: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ).**          sh
aef0: 61 6c 6c 20 73 65 74 20 74 68 65 20 64 65 66 61  all set the defa
af00: 75 6c 74 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ult [threading m
af10: 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
af20: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  read..**.** {H14
af30: 31 32 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  126} A successfu
af40: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
af50: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
af60: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
af70: 49 5a 45 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20  IZED]).**       
af80: 20 20 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65     shall set the
af90: 20 64 65 66 61 75 6c 74 20 5b 74 68 72 65 61 64   default [thread
afa0: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
afb0: 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  ialized..**.** {
afc0: 48 31 34 31 32 39 7d 20 41 20 73 75 63 63 65 73  H14129} A succes
afd0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
afe0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
aff0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
b000: 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 20 20  EX],X).**       
b010: 20 20 20 77 68 65 72 65 20 58 20 69 73 20 61 20     where X is a 
b020: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
b030: 69 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c 69 74  itialized [sqlit
b040: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
b050: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  ].**          ob
b060: 6a 65 63 74 20 73 68 61 6c 6c 20 63 61 75 73 65  ject shall cause
b070: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
b080: 6d 75 74 65 78 20 6f 70 65 72 61 74 69 6f 6e 73  mutex operations
b090: 20 70 65 72 66 6f 72 6d 65 64 0a 2a 2a 20 20 20   performed.**   
b0a0: 20 20 20 20 20 20 20 62 79 20 53 51 4c 69 74 65         by SQLite
b0b0: 20 74 6f 20 75 73 65 20 74 68 65 20 6d 75 74 65   to use the mute
b0c0: 78 20 6d 65 74 68 6f 64 73 20 74 68 61 74 20 77  x methods that w
b0d0: 65 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20 58  ere present in X
b0e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75 72  .**          dur
b0f0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  ing the call to 
b100: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
b110: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 33  )]..**.** {H1413
b120: 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  2} A successful 
b130: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
b140: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
b150: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
b160: 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  ],X).**         
b170: 20 77 68 65 72 65 20 58 20 69 73 20 61 20 70 6f   where X is a po
b180: 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
b190: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
b1a0: 64 73 5d 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 20  ds] object .**  
b1b0: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 6f 76          shall ov
b1c0: 65 72 77 72 69 74 65 20 74 68 65 20 63 6f 6e 74  erwrite the cont
b1d0: 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ent of [sqlite3_
b1e0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 6f  mutex_methods] o
b1f0: 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 20 20  bject.**        
b200: 20 20 77 69 74 68 20 74 68 65 20 6d 75 74 65 78    with the mutex
b210: 20 6d 65 74 68 6f 64 73 20 63 75 72 72 65 6e 74   methods current
b220: 6c 79 20 69 6e 20 75 73 65 20 62 79 20 53 51 4c  ly in use by SQL
b230: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31  ite..**.** {H141
b240: 33 35 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  35} A successful
b250: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
b260: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
b270: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
b280: 2c 4d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ,M).**          
b290: 77 68 65 72 65 20 4d 20 69 73 20 61 20 70 6f 69  where M is a poi
b2a0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 69 74 69  nter to an initi
b2b0: 61 6c 69 7a 65 64 20 5b 73 71 6c 69 74 65 33 5f  alized [sqlite3_
b2c0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
b2d0: 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20           object 
b2e0: 73 68 61 6c 6c 20 63 61 75 73 65 20 61 6c 6c 20  shall cause all 
b2f0: 73 75 62 73 65 71 75 65 6e 74 20 6d 65 6d 6f 72  subsequent memor
b300: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 70 65  y allocation ope
b310: 72 61 74 69 6f 6e 73 0a 2a 2a 20 20 20 20 20 20  rations.**      
b320: 20 20 20 20 70 65 72 66 6f 72 6d 65 64 20 62 79      performed by
b330: 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 74   SQLite to use t
b340: 68 65 20 6d 65 74 68 6f 64 73 20 74 68 61 74 20  he methods that 
b350: 77 65 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20  were present in 
b360: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20 64  .**          M d
b370: 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 74  uring the call t
b380: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b390: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  g()]..**.** {H14
b3a0: 31 33 38 7d 20 41 20 73 75 63 63 65 73 73 66 75  138} A successfu
b3b0: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
b3c0: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b3d0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
b3e0: 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20 20 20  LOC],M).**      
b3f0: 20 20 20 20 77 68 65 72 65 20 4d 20 69 73 20 61      where M is a
b400: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
b410: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
b420: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 73 68 61 6c  ods] object shal
b430: 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76  l.**          ov
b440: 65 72 77 72 69 74 65 20 74 68 65 20 63 6f 6e 74  erwrite the cont
b450: 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ent of [sqlite3_
b460: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  mem_methods] obj
b470: 65 63 74 20 77 69 74 68 20 0a 2a 2a 20 20 20 20  ect with .**    
b480: 20 20 20 20 20 20 74 68 65 20 6d 65 6d 6f 72 79        the memory
b490: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6d 65 74 68   allocation meth
b4a0: 6f 64 73 20 63 75 72 72 65 6e 74 6c 79 20 69 6e  ods currently in
b4b0: 20 75 73 65 20 62 79 0a 2a 2a 20 20 20 20 20 20   use by.**      
b4c0: 20 20 20 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a      SQLite..**.*
b4d0: 2a 20 7b 48 31 34 31 34 31 7d 20 41 20 73 75 63  * {H14141} A suc
b4e0: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
b4f0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
b500: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
b510: 4d 45 4d 53 54 41 54 55 53 5d 2c 31 29 0a 2a 2a  MEMSTATUS],1).**
b520: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
b530: 65 6e 61 62 6c 65 20 74 68 65 20 6d 65 6d 6f 72  enable the memor
b540: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
b550: 74 75 73 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c  tus collection l
b560: 6f 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  ogic..**.** {H14
b570: 31 34 34 7d 20 41 20 73 75 63 63 65 73 73 66 75  144} A successfu
b580: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
b590: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b5a0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
b5b0: 54 55 53 5d 2c 30 29 0a 2a 2a 20 20 20 20 20 20  TUS],0).**      
b5c0: 20 20 20 20 73 68 61 6c 6c 20 64 69 73 61 62 6c      shall disabl
b5d0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
b5e0: 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63  ocation status c
b5f0: 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 2e  ollection logic.
b600: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 37 7d 20  .**.** {H14147} 
b610: 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
b620: 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63 6f 6c  ation status col
b630: 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 20 73 68  lection logic sh
b640: 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20  all be.**       
b650: 20 20 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65     enabled by de
b660: 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fault..**.** {H1
b670: 34 31 35 30 7d 20 41 20 73 75 63 63 65 73 73 66  4150} A successf
b680: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
b690: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
b6a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
b6b0: 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20  CH],S,Z,N).**   
b6c0: 20 20 20 20 20 20 20 77 68 65 72 65 20 5a 20 61         where Z a
b6d0: 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65 67  nd N are non-neg
b6e0: 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 20 61  ative integers a
b6f0: 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nd .**          
b700: 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  S is a pointer t
b710: 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d 65 6d  o an aligned mem
b720: 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 20 6c  ory buffer not l
b730: 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  ess than.**     
b740: 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73 20 69       Z*N bytes i
b750: 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63 61 75  n size shall cau
b760: 73 65 20 53 20 74 6f 20 62 65 20 75 73 65 64 20  se S to be used 
b770: 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
b780: 20 20 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f     [scratch memo
b790: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f  ry allocator] fo
b7a0: 72 20 61 73 20 6d 61 6e 79 20 61 73 20 4e 20 73  r as many as N s
b7b0: 69 6d 75 6c 61 74 61 6e 65 6f 75 73 0a 2a 2a 20  imulataneous.** 
b7c0: 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74           allocat
b7d0: 69 6f 6e 73 20 65 61 63 68 20 6f 66 20 73 69 7a  ions each of siz
b7e0: 65 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31  e Z..**.** {H141
b7f0: 35 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  53} A successful
b800: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
b810: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
b820: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
b830: 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20  ],S,Z,N).**     
b840: 20 20 20 20 20 77 68 65 72 65 20 53 20 69 73 20       where S is 
b850: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  a NULL pointer s
b860: 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65  hall disable the
b870: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 63  .**          [sc
b880: 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c  ratch memory all
b890: 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ocator]..**.** {
b8a0: 48 31 34 31 35 36 7d 20 41 20 73 75 63 63 65 73  H14156} A succes
b8b0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  sful call to.** 
b8c0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
b8d0: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
b8e0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
b8f0: 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20  HE],S,Z,N).**   
b900: 20 20 20 20 20 20 20 77 68 65 72 65 20 5a 20 61         where Z a
b910: 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65 67  nd N are non-neg
b920: 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 20 61  ative integers a
b930: 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nd .**          
b940: 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  S is a pointer t
b950: 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d 65 6d  o an aligned mem
b960: 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 20 6c  ory buffer not l
b970: 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  ess than.**     
b980: 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73 20 69       Z*N bytes i
b990: 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63 61 75  n size shall cau
b9a0: 73 65 20 53 20 74 6f 20 62 65 20 75 73 65 64 20  se S to be used 
b9b0: 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
b9c0: 20 20 20 5b 70 61 67 65 63 61 63 68 65 20 6d 65     [pagecache me
b9d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
b9e0: 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73 20 4e  for as many as N
b9f0: 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73 0a 2a   simulataneous.*
ba00: 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63  *          alloc
ba10: 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66 20 73  ations each of s
ba20: 69 7a 65 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ize Z..**.** {H1
ba30: 34 31 35 39 7d 20 41 20 73 75 63 63 65 73 73 66  4159} A successf
ba40: 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20  ul call to.**   
ba50: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
ba60: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
ba70: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
ba80: 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20  ],S,Z,N).**     
ba90: 20 20 20 20 20 77 68 65 72 65 20 53 20 69 73 20       where S is 
baa0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  a NULL pointer s
bab0: 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65  hall disable the
bac0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 61  .**          [pa
bad0: 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  gecache memory a
bae0: 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a  llocator]..**.**
baf0: 20 7b 48 31 34 31 36 32 7d 20 41 20 73 75 63 63   {H14162} A succ
bb00: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
bb10: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
bb20: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
bb30: 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20  EAP],H,Z,N).**  
bb40: 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a 20          where Z 
bb50: 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65  and N are non-ne
bb60: 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 20  gative integers 
bb70: 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  and .**         
bb80: 20 48 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20   H is a pointer 
bb90: 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d 65  to an aligned me
bba0: 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 20  mory buffer not 
bbb0: 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20  less than.**    
bbc0: 20 20 20 20 20 20 5a 20 62 79 74 65 73 20 69 6e        Z bytes in
bbd0: 20 73 69 7a 65 20 73 68 61 6c 6c 20 65 6e 61 62   size shall enab
bbe0: 6c 65 20 74 68 65 20 5b 6d 65 6d 73 79 73 35 5d  le the [memsys5]
bbf0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
bc00: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  r.**          an
bc10: 64 20 63 61 75 73 65 20 69 74 20 74 6f 20 75 73  d cause it to us
bc20: 65 20 62 75 66 66 65 72 20 53 20 61 73 20 69 74  e buffer S as it
bc30: 73 20 6d 65 6d 6f 72 79 20 73 6f 75 72 63 65 20  s memory source 
bc40: 61 6e 64 20 74 6f 20 75 73 65 0a 2a 2a 20 20 20  and to use.**   
bc50: 20 20 20 20 20 20 20 61 20 6d 69 6e 69 6d 75 6d         a minimum
bc60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
bc70: 20 6f 66 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   of N..**.** {H1
bc80: 34 31 36 35 7d 20 41 20 73 75 63 63 65 73 73 66  4165} A successf
bc90: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
bca0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
bcb0: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
bcc0: 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20  ,H,Z,N).**      
bcd0: 20 20 20 20 77 68 65 72 65 20 48 20 69 73 20 61      where H is a
bce0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73 68   NULL pointer sh
bcf0: 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65 0a  all disable the.
bd00: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 6d 65 6d  **          [mem
bd10: 73 79 73 35 5d 20 6d 65 6d 6f 72 79 20 61 6c 6c  sys5] memory all
bd20: 6f 63 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ocator..**.** {H
bd30: 31 34 31 36 38 7d 20 41 20 73 75 63 63 65 73 73  14168} A success
bd40: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
bd50: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
bd60: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
bd70: 41 53 49 44 45 5d 2c 5a 2c 4e 29 0a 2a 2a 20 20  ASIDE],Z,N).**  
bd80: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 63 61          shall ca
bd90: 75 73 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  use the default 
bda0: 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
bdb0: 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
bdc0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 20 20  figuration.**   
bdd0: 20 20 20 20 20 20 20 66 6f 72 20 6e 65 77 20 5b         for new [
bde0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
bdf0: 69 6f 6e 73 5d 20 74 6f 20 62 65 20 4e 20 73 6c  ions] to be N sl
be00: 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73 20 65  ots of Z bytes e
be10: 61 63 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ach..*/.SQLITE_E
be20: 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
be30: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
be40: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
be50: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
be60: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
be70: 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 32  nnections  {H142
be80: 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20  00} <S20000>.** 
be90: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
bea0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
beb0: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
bec0: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
bed0: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
bee0: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
bef0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
bf00: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
bf10: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
bf20: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
bf30: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
bf40: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
bf50: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
bf60: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
bf70: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
bf80: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
bf90: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
bfa0: 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  ).  The.** sqlit
bfb0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
bfc0: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c  nterface can onl
bfd0: 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69  y be used immedi
bfe0: 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74  ately after.** t
bff0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
c000: 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  ection is create
c010: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c020: 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _open()],.** [sq
c030: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
c040: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
c050: 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a  n_v2()].  .**.**
c060: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
c070: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c080: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
c090: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  .)  is the.** co
c0a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
c0b0: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
c0c0: 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  de that indicate
c0d0: 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74  s what.** aspect
c0e0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
c0f0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
c100: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
c110: 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63  d..** The only c
c120: 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76  hoice for this v
c130: 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  alue is [SQLITE_
c140: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
c150: 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62  DE]..** New verb
c160: 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
c170: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
c180: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
c190: 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69  QLite..** Additi
c1a0: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64  onal arguments d
c1b0: 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72  epend on the ver
c1c0: 62 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  b..**.** INVARIA
c1d0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32  NTS:.**.** {H142
c1e0: 30 33 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  03} A call to [s
c1f0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c200: 28 44 2c 56 2c 2e 2e 2e 29 5d 20 73 68 61 6c 6c  (D,V,...)] shall
c210: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
c220: 4f 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  OK].**          
c230: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
c240: 68 65 20 63 61 6c 6c 20 69 73 20 73 75 63 63 65  he call is succe
c250: 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ssful..**.** {H1
c260: 34 32 30 36 7d 20 49 66 20 6f 6e 65 20 6f 72 20  4206} If one or 
c270: 6d 6f 72 65 20 73 6c 6f 74 73 20 6f 66 20 74 68  more slots of th
c280: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  e [lookaside mem
c290: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66  ory allocator] f
c2a0: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
c2b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c2c0: 69 6f 6e 5d 20 44 20 61 72 65 20 69 6e 20 75 73  ion] D are in us
c2d0: 65 2c 20 74 68 65 6e 20 61 20 63 61 6c 6c 20 74  e, then a call t
c2e0: 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
c2f0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c300: 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ](D,[SQLITE_DBCO
c310: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
c320: 2e 2e 2e 29 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  ...) shall.**   
c330: 20 20 20 20 20 20 20 66 61 69 6c 20 77 69 74 68         fail with
c340: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59   an [SQLITE_BUSY
c350: 5d 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0a 2a  ] return code..*
c360: 2a 0a 2a 2a 20 7b 48 31 34 32 30 39 7d 20 41 20  *.** {H14209} A 
c370: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
c380: 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  to .**          
c390: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
c3a0: 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42  ig](D,[SQLITE_DB
c3b0: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
c3c0: 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a  ],B,Z,N) where.*
c3d0: 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73 20  *          D is 
c3e0: 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  an open [databas
c3f0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
c400: 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 70 6f  d Z and N are po
c410: 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  sitive.**       
c420: 20 20 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20     integers and 
c430: 42 20 69 73 20 61 6e 20 61 6c 69 67 6e 65 64 20  B is an aligned 
c440: 62 75 66 66 65 72 20 61 74 20 6c 65 61 73 74 20  buffer at least 
c450: 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  Z*N bytes in siz
c460: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  e.**          sh
c470: 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 5b 6c  all cause the [l
c480: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
c490: 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44  allocator] for D
c4a0: 20 74 6f 20 75 73 65 20 62 75 66 66 65 72 20 42   to use buffer B
c4b0: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69   .**          wi
c4c0: 74 68 20 4e 20 73 6c 6f 74 73 20 6f 66 20 5a 20  th N slots of Z 
c4d0: 62 79 74 65 73 20 65 61 63 68 2e 0a 2a 2a 0a 2a  bytes each..**.*
c4e0: 2a 20 7b 48 31 34 32 31 32 7d 20 41 20 73 75 63  * {H14212} A suc
c4f0: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
c500: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
c510: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 5d  lite3_db_config]
c520: 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  (D,[SQLITE_DBCON
c530: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42  FIG_LOOKASIDE],B
c540: 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a 2a 20 20  ,Z,N) where.**  
c550: 20 20 20 20 20 20 20 20 44 20 69 73 20 61 6e 20          D is an 
c560: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
c570: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5a  onnection] and Z
c580: 20 61 6e 64 20 4e 20 61 72 65 20 70 6f 73 69 74   and N are posit
c590: 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
c5a0: 69 6e 74 65 67 65 72 73 20 61 6e 64 20 42 20 69  integers and B i
c5b0: 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  s NULL pointer s
c5c0: 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 0a 2a  hall cause the.*
c5d0: 2a 20 20 20 20 20 20 20 20 20 20 5b 6c 6f 6f 6b  *          [look
c5e0: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
c5f0: 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44 20 74 6f  ocator] for D to
c600: 20 61 20 6f 62 74 61 69 6e 20 5a 2a 4e 20 62 79   a obtain Z*N by
c610: 74 65 20 62 75 66 66 65 72 0a 2a 2a 20 20 20 20  te buffer.**    
c620: 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 70        from the p
c630: 72 69 6d 61 72 79 20 6d 65 6d 6f 72 79 20 61 6c  rimary memory al
c640: 6c 6f 63 61 74 6f 72 20 61 6e 64 20 75 73 65 20  locator and use 
c650: 74 68 61 74 20 62 75 66 66 65 72 0a 2a 2a 20 20  that buffer.**  
c660: 20 20 20 20 20 20 20 20 77 69 74 68 20 4e 20 6c          with N l
c670: 6f 6f 6b 61 73 69 64 65 20 73 6c 6f 74 73 20 6f  ookaside slots o
c680: 66 20 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a  f Z bytes each..
c690: 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31 35 7d 20 41  **.** {H14215} A
c6a0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
c6b0: 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   to .**         
c6c0: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
c6d0: 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44  fig](D,[SQLITE_D
c6e0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
c6f0: 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a  E],B,Z,N) where.
c700: 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73  **          D is
c710: 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61   an open [databa
c720: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
c730: 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 7a  nd Z and N are z
c740: 65 72 6f 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20  ero shall.**    
c750: 20 20 20 20 20 20 64 69 73 61 62 6c 65 20 74 68        disable th
c760: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  e [lookaside mem
c770: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66  ory allocator] f
c780: 6f 72 20 44 2e 0a 2a 2a 0a 2a 2a 0a 2a 2f 0a 53  or D..**.**.*/.S
c790: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
c7a0: 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  AL int sqlite3_d
c7b0: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
c7c0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
c7d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c7e0: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
c7f0: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31  ion Routines {H1
c800: 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a  0155} <S20120>.*
c810: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
c820: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
c830: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
c840: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
c850: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
c860: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
c870: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
c880: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
c890: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
c8a0: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
c8b0: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
c8c0: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
c8d0: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
c8e0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
c8f0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
c900: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
c910: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
c920: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
c930: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
c940: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
c950: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
c960: 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74  LLOC].  By creat
c970: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
c980: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
c990: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
c9a0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
c9b0: 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f  fig()] during co
c9c0: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a  nfiguration, an.
c9d0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  ** application c
c9e0: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
c9f0: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
ca00: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
ca10: 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c  ystem.** for SQL
ca20: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
ca30: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
ca40: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
ca50: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
ca60: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
ca70: 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  h a built-in mem
ca80: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
ca90: 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74  at is.** perfect
caa0: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
cab0: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
cac0: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
cad0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
cae0: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
caf0: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
cb00: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
cb10: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
cb20: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
cb30: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
cb40: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
cb50: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
cb60: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
cb70: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
cb80: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
cb90: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
cba0: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
cbb0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
cbc0: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
cbd0: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
cbe0: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
cbf0: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
cc00: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
cc10: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
cc20: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
cc30: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
cc40: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
cc50: 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64  lloc, xFree, and
cc60: 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64   xRealloc method
cc70: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
cc80: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
cc90: 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65  , free(), and re
cca0: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e  alloc() function
ccb0: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
ccc0: 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ard library..**.
ccd0: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
cce0: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
ccf0: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
cd00: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
cd10: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
cd20: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
cd30: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
cd40: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
cd50: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
cd60: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
cd70: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
cd80: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
cd90: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
cda0: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
cdb0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
cdc0: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
cdd0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
cde0: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
cdf0: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
ce00: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
ce10: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
ce20: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
ce30: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
ce40: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ce50: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
ce60: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
ce70: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
ce80: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
ce90: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
cea0: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
ceb0: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a   power of 2..**.
cec0: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
ced0: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
cee0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
cef0: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
cf00: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
cf10: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
cf20: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
cf30: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
cf40: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
cf50: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
cf60: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
cf70: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
cf80: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
cf90: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
cfa0: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
cfb0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
cfc0: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
cfd0: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
cfe0: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
cff0: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
d000: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
d010: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
d020: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79  xShutdown..*/.ty
d030: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
d040: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d050: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
d060: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
d070: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d080: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
d090: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
d0a0: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
d0b0: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
d0c0: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
d0d0: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
d0e0: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
d0f0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
d100: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
d110: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
d120: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
d130: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
d140: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
d150: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
d160: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
d170: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
d180: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
d190: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
d1a0: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
d1b0: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
d1c0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
d1d0: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
d1e0: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
d1f0: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
d200: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
d210: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
d220: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
d230: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
d240: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
d250: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
d260: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
d270: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
d280: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
d290: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
d2a0: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
d2b0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
d2c0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
d2d0: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31  tion Options {H1
d2e0: 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0160} <S20000>.*
d2f0: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
d300: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
d310: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
d320: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
d330: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d340: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
d350: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
d360: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
d370: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
d380: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
d390: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
d3a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d3b0: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
d3c0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
d3d0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
d3e0: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
d3f0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d400: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
d410: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
d420: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
d430: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
d440: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
d450: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d460: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
d470: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
d480: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
d490: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
d4a0: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
d4b0: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
d4c0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
d4d0: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
d4e0: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
d4f0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d500: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
d510: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
d520: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d530: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
d540: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
d550: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
d560: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
d570: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e  on.  This option
d580: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
d590: 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
d5a0: 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
d5b0: 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
d5c0: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
d5d0: 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
d5e0: 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  hread.</dd>.**.*
d5f0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d600: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
d610: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
d620: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
d630: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
d640: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
d650: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
d660: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
d670: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
d680: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
d690: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
d6a0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
d6b0: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
d6c0: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
d6d0: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
d6e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d6f0: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
d700: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
d710: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
d720: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
d730: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
d740: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
d750: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
d760: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
d770: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
d780: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
d790: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
d7a0: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
d7b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d7c0: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
d7d0: 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65 20 5b  time.  See the [
d7e0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 0a  threading mode].
d7f0: 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  ** documentation
d800: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
d810: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64  information.</dd
d820: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d830: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
d840: 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
d850: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
d860: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
d870: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
d880: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
d890: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
d8a0: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
d8b0: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
d8c0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
d8d0: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
d8e0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
d8f0: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
d900: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
d910: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
d920: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
d930: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d940: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
d950: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
d960: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
d970: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
d980: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
d990: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d9a0: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
d9b0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
d9c0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
d9d0: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
d9e0: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
d9f0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
da00: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
da10: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
da20: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
da30: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
da40: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
da50: 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  ..** See the [th
da60: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
da70: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
da80: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
da90: 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  mation.</dd>.**.
daa0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
dab0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
dac0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
dad0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
dae0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
daf0: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
db00: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
db10: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
db20: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
db30: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
db40: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
db50: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
db60: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
db70: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
db80: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
db90: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
dba0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
dbb0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
dbc0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
dbd0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
dbe0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
dbf0: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
dc00: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
dc10: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
dc20: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
dc30: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
dc40: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
dc50: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
dc60: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
dc70: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
dc80: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
dc90: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
dca0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
dcb0: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
dcc0: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
dcd0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
dce0: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
dcf0: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
dd00: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
dd10: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
dd20: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
dd30: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
dd40: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
dd50: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
dd60: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
dd70: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
dd80: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
dd90: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
dda0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
ddb0: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
ddc0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
ddd0: 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
dde0: 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
ddf0: 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
de00: 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
de10: 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
de20: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
de30: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
de40: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
de50: 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 57  ** statistics. W
de60: 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68  hen disabled, th
de70: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
de80: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
de90: 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65  come .** non-ope
dea0: 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
deb0: 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
dec0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
ded0: 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
dee0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
def0: 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
df00: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
df10: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
df20: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
df30: 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
df40: 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f  **   </ul>.** </
df50: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
df60: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
df70: 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
df80: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
df90: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
dfa0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
dfb0: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
dfc0: 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
dfd0: 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
dfe0: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
dff0: 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74  ts:  A pointer t
e000: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68  o the memory, th
e010: 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
e020: 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  h scratch buffer
e030: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
e040: 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72 73  umber of buffers
e050: 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a   (N).  The sz.**
e060: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
e070: 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  e a multiple of 
e080: 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61 6d  16. The sz param
e090: 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61  eter should be a
e0a0: 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c 61   few bytes.** la
e0b0: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61 63  rger than the ac
e0c0: 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70 61  tual scratch spa
e0d0: 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65 20  ce required due 
e0e0: 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61  internal overhea
e0f0: 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 0a  d..** The first.
e100: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
e110: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
e120: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
e130: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
e140: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   of memory..** S
e150: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
e160: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  o more than one 
e170: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 61  scratch buffer a
e180: 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61  t once per threa
e190: 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  d, so.** N shoul
e1a0: 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20  d be set to the 
e1b0: 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
e1c0: 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
e1d0: 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70  ds.  The sz.** p
e1e0: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
e1f0: 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20 73  be 6 times the s
e200: 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
e210: 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
e220: 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63   size..** Scratc
e230: 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75 73  h buffers are us
e240: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
e250: 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20  e btree balance 
e260: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a  operation.  If.*
e270: 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c 61  * The btree bala
e280: 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69 74  ncer needs addit
e290: 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79  ional memory bey
e2a0: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
e2b0: 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74  ided by.** scrat
e2c0: 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69 66  ch buffers or if
e2d0: 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66 66   no scratch buff
e2e0: 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65 63  er space is spec
e2f0: 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69  ified, then SQLi
e300: 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73  te.** goes to [s
e310: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
e320: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
e330: 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c  emory it needs.<
e340: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e350: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
e360: 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
e370: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
e380: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
e390: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
e3a0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
e3b0: 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64  use for.** the d
e3c0: 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
e3d0: 68 65 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  he.  There are t
e3e0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
e3f0: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
e400: 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  .** memory, the 
e410: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
e420: 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  e buffer (sz), a
e430: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
e440: 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   pages (N)..** T
e450: 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d  he sz argument m
e460: 75 73 74 20 62 65 20 61 20 70 6f 77 65 72 20 6f  ust be a power o
e470: 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
e480: 32 20 61 6e 64 20 33 32 37 36 38 2e 20 20 54 68  2 and 32768.  Th
e490: 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
e4a0: 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
e4b0: 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
e4c0: 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  n of at least sz
e4d0: 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
e4e0: 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  ry..** SQLite wi
e4f0: 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
e500: 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
e510: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
e520: 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
e530: 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
e540: 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
e550: 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
e560: 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 49 66  ds to cache.  If
e570: 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
e580: 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
e590: 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
e5a0: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
e5b0: 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
e5c0: 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
e5d0: 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
e5e0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
e5f0: 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
e600: 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
e610: 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * The implementa
e620: 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65 20 6f  tion might use o
e630: 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
e640: 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f 20 68  e N buffers to h
e650: 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  old .** memory a
e660: 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d  ccounting inform
e670: 61 74 69 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ation. </dd>.**.
e680: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e690: 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
e6a0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
e6b0: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
e6c0: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
e6d0: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  er that SQLite w
e6e0: 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61  ill use.** for a
e6f0: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
e700: 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
e710: 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64  ion needs beyond
e720: 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a   those provided.
e730: 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ** for by [SQLIT
e740: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
e750: 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f  ] and [SQLITE_CO
e760: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
e770: 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
e780: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41  ree arguments: A
e790: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
e7a0: 6d 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62  memory, the numb
e7b0: 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
e7c0: 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
e7d0: 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
e7e0: 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
e7f0: 73 69 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65  size.  If.** the
e800: 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
e810: 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
e820: 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
e830: 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
e840: 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
e850: 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
e860: 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
e870: 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
e880: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
e890: 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
e8a0: 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
e8b0: 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
e8c0: 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74  G_MALLOC].  If t
e8d0: 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
e8e0: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
e8f0: 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
e900: 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
e910: 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
e920: 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
e930: 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
e940: 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
e950: 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
e960: 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
e970: 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
e980: 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
e990: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
e9a0: 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  eds.</dd>.**.** 
e9b0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
e9c0: 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
e9d0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
e9e0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
e9f0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
ea00: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
ea10: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
ea20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
ea30: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
ea40: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
ea50: 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
ea60: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
ea70: 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
ea80: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
ea90: 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68  d in place.** th
eaa0: 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
eab0: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
eac0: 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  te.</dd>.**.** <
ead0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
eae0: 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
eaf0: 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
eb00: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
eb10: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
eb20: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
eb30: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
eb40: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
eb50: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
eb60: 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
eb70: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
eb80: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
eb90: 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
eba0: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
ebb0: 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
ebc0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68   routines..** Th
ebd0: 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
ebe0: 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
ebf0: 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
ec00: 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
ec10: 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
ec20: 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
ec30: 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
ec40: 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
ec50: 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
ec60: 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
ec70: 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a   example.</dd>.*
ec80: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
ec90: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
eca0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
ecb0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
ecc0: 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
ecd0: 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
ece0: 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
ecf0: 79 20 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b  y allcation look
ed00: 61 73 69 64 65 20 6f 70 74 69 6d 69 7a 61 74 69  aside optimizati
ed10: 6f 6e 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  on.  The first a
ed20: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
ed30: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
ed40: 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
ed50: 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
ed60: 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
ed70: 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
ed80: 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
ed90: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
eda0: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
edb0: 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
edc0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
edd0: 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
ede0: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
edf0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
ee00: 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
ee10: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
ee20: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
ee30: 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
ee40: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
ee50: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
ee60: 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
ee70: 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
ee80: 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
ee90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
eea0: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
eeb0: 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
eec0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
eed0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
eee0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
eef0: 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
ef00: 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
ef10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ef20: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
ef30: 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
ef40: 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
ef50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
ef60: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
ef70: 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
ef80: 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
ef90: 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
efa0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
efb0: 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
efc0: 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
efd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
efe0: 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
eff0: 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
f000: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
f010: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
f020: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
f030: 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
f040: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
f050: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
f060: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
f070: 55 4e 4b 41 4c 4c 4f 43 20 20 20 31 32 20 20 2f  UNKALLOC   12  /
f080: 2a 20 69 6e 74 20 74 68 72 65 73 68 6f 6c 64 20  * int threshold 
f090: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f0a0: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
f0b0: 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
f0c0: 20 69 6e 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43   int */../*.** C
f0d0: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
f0e0: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b  ration Options {
f0f0: 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30 30 3e  H10170} <S20000>
f100: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
f110: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
f120: 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
f130: 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
f140: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f150: 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
f160: 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
f170: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
f180: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
f190: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
f1a0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
f1b0: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
f1c0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
f1d0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
f1e0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
f1f0: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
f200: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
f210: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
f220: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
f230: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
f240: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
f250: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
f260: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
f270: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
f280: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
f290: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
f2a0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
f2b0: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
f2c0: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
f2d0: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
f2e0: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
f2f0: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
f300: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
f310: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f320: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
f330: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
f340: 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
f350: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
f360: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
f370: 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
f380: 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
f390: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
f3a0: 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
f3b0: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
f3c0: 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
f3d0: 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
f3e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f3f0: 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ion]..** The fir
f400: 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
f410: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
f420: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
f430: 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
f440: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
f450: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
f460: 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
f470: 65 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 20 66  e memory.  The f
f480: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
f490: 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
f4a0: 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
f4b0: 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
f4c0: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
f4d0: 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
f4e0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
f4f0: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 73 65  lloc()].  The se
f500: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
f510: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
f520: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
f530: 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
f540: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
f550: 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  t is the number 
f560: 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68  of.** slots.  Th
f570: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
f580: 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  ffer in the firs
f590: 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
f5a0: 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a  be greater than.
f5b0: 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74  ** or equal to t
f5c0: 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68  he product of th
f5d0: 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
f5e0: 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 3c 2f 64  rd arguments.</d
f5f0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
f600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f610: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
f620: 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20  IDE    1001  /* 
f630: 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
f640: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
f650: 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
f660: 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
f670: 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32 32  sult Codes {H122
f680: 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  00} <S10700>.**.
f690: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
f6a0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
f6b0: 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
f6c0: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
f6d0: 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
f6e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
f6f0: 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
f700: 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ite. The extende
f710: 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
f720: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
f730: 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
f740: 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
f750: 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72 61  bility considera
f760: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  tions..**.** INV
f770: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
f780: 48 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65 77  H12201} Each new
f790: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f7a0: 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76  ction] shall hav
f7b0: 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  e the.**        
f7c0: 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75    [extended resu
f7d0: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
f7e0: 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
f7f0: 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fault..**.** {H1
f800: 32 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  2202} The [sqlit
f810: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
f820: 6c 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20 69  lt_codes(D,F)] i
f830: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 65  nterface shall e
f840: 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20  nable.**        
f850: 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75    [extended resu
f860: 6c 74 20 63 6f 64 65 73 5d 20 66 6f 72 20 74 68  lt codes] for th
f870: 65 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  e  [database con
f880: 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20  nection] D.**   
f890: 20 20 20 20 20 20 20 69 66 20 74 68 65 20 46 20         if the F 
f8a0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 72 75  parameter is tru
f8b0: 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  e, or disable th
f8c0: 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73 65  em if F is false
f8d0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
f8e0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
f8f0: 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
f900: 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
f910: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
f920: 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20  st Insert Rowid 
f930: 7b 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30 30  {H12220} <S10700
f940: 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74  >.**.** Each ent
f950: 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
f960: 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
f970: 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
f980: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
f990: 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77 69  called the "rowi
f9a0: 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  d". The rowid is
f9b0: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
f9c0: 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
f9d0: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
f9e0: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
f9f0: 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
fa00: 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
fa10: 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
fa20: 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
fa30: 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
fa40: 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20  umns. If.** the 
fa50: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
fa60: 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45 47  mn of type INTEG
fa70: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20 74  ER PRIMARY KEY t
fa80: 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
fa90: 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
faa0: 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
fab0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  d..**.** This ro
fac0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
fad0: 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20 6d  e rowid of the m
fae0: 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
faf0: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
fb00: 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  ] into the datab
fb10: 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61  ase from the [da
fb20: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fb30: 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
fb40: 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66  st argument.  If
fb50: 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b   no successful [
fb60: 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65  INSERT]s.** have
fb70: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
fb80: 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20  n that database 
fb90: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f  connection, zero
fba0: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
fbb0: 0a 2a 2a 20 49 66 20 61 6e 20 5b 49 4e 53 45 52  .** If an [INSER
fbc0: 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
fbd0: 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e   a trigger, then
fbe0: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
fbf0: 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
fc00: 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
fc10: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
fc20: 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
fc30: 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gger is running.
fc40: 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
fc50: 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
fc60: 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
fc70: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
fc80: 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72  routine.** rever
fc90: 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
fca0: 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
fcb0: 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
fcc0: 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e   fired..**.** An
fcd0: 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
fce0: 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
fcf0: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
fd00: 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
fd10: 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
fd20: 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
fd30: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
fd40: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
fd50: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54  s.** routine.  T
fd60: 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
fd70: 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
fd80: 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
fd90: 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
fda0: 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
fdb0: 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
fdc0: 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
fdd0: 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
fde0: 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
fdf0: 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
fe00: 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54  ls.  When INSERT
fe10: 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
fe20: 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
fe30: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
fe40: 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
fe50: 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
fe60: 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
fe70: 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
fe80: 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
fe90: 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
fea0: 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
feb0: 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
fec0: 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
fed0: 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
fee0: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
fef0: 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
ff00: 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  ce..**.** For th
ff10: 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
ff20: 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b  is routine, an [
ff30: 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69  INSERT] is consi
ff40: 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73  dered to.** be s
ff50: 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69  uccessful even i
ff60: 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65  f it is subseque
ff70: 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ntly rolled back
ff80: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
ff90: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32  TS:.**.** {H1222
ffa0: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
ffb0: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
ffc0: 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  d()] function sh
ffd0: 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 72  all return the r
ffe0: 6f 77 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  owid.**         
fff0: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
10000 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b  ent successful [
10010 49 4e 53 45 52 54 5d 20 70 65 72 66 6f 72 6d 65  INSERT] performe
10020 64 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  d on the same.**
10030 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
10040 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10050 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20 73  and within the s
10060 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 6c 65  ame or higher le
10070 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  vel.**          
10080 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c  trigger context,
10090 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72   or zero if ther
100a0 65 20 68 61 76 65 20 62 65 65 6e 20 6e 6f 20 71  e have been no q
100b0 75 61 6c 69 66 79 69 6e 67 0a 2a 2a 20 20 20 20  ualifying.**    
100c0 20 20 20 20 20 20 5b 49 4e 53 45 52 54 5d 20 73        [INSERT] s
100d0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
100e0 20 7b 48 31 32 32 32 33 7d 20 54 68 65 20 5b 73   {H12223} The [s
100f0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
10100 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63  rt_rowid()] func
10110 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72  tion shall retur
10120 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
10130 20 20 73 61 6d 65 20 76 61 6c 75 65 20 77 68 65    same value whe
10140 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
10150 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 20 63  e same trigger c
10160 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20  ontext.**       
10170 20 20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62     immediately b
10180 65 66 6f 72 65 20 61 6e 64 20 61 66 74 65 72 20  efore and after 
10190 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  a [ROLLBACK]..**
101a0 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
101b0 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 33 32 7d 20  .**.** {A12232} 
101c0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
101d0 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
101e0 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
101f0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
10200 20 20 20 20 20 64 61 74 61 62 61 73 65 20 63 6f       database co
10210 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
10220 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
10230 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
10240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
10250 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
10260 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
10270 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
10280 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20  t rowid,.**     
10290 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 76 61       then the va
102a0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
102b0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
102c0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
102d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 70  .**          unp
102e0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
102f0 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
10300 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
10310 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20   the new.**     
10320 20 20 20 20 20 6c 61 73 74 20 69 6e 73 65 72 74       last insert
10330 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74   rowid..*/.sqlit
10340 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
10350 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
10360 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
10370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10380 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
10390 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
103a0 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30   {H12240} <S1060
103b0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
103c0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
103d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
103e0 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
103f0 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
10400 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
10410 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
10420 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
10430 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
10440 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
10450 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10460 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
10470 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
10480 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68  eter..** Only ch
10490 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
104a0 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
104b0 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
104c0 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
104d0 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
104e0 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
104f0 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
10500 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
10510 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20  ** triggers are 
10520 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65  not counted. Use
10530 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
10540 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
10550 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69  unction.** to fi
10560 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
10570 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
10580 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
10590 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
105a0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f  ers..**.** A "ro
105b0 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
105c0 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
105d0 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
105e0 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
105f0 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
10600 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
10610 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
10620 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
10630 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
10640 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43  ffects of REPLAC
10650 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
10660 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
10670 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
10680 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42  essing, DROP TAB
10690 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  LE, or by any ot
106a0 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
106b0 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
106c0 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
106d0 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  nges..**.** A "t
106e0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
106f0 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
10700 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
10710 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
10720 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
10730 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d  of a trigger.  M
10740 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
10750 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
10760 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
10770 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
10780 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
10790 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
107a0 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
107b0 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
107c0 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
107d0 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
107e0 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
107f0 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
10800 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
10810 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
10820 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
10830 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
10840 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
10850 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
10860 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
10870 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
10880 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
10890 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
108a0 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
108b0 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
108c0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
108d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
108e0 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
108f0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
10900 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
10910 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
10920 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
10930 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
10940 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
10950 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73  text..**.** Thus
10960 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  , when called fr
10970 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
10980 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
10990 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e  returns the.** n
109a0 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
109b0 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
109c0 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
109d0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
109e0 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72   that also occur
109f0 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c  red at the top l
10a00 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68  evel.  Within th
10a10 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
10a20 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
10a30 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
10a40 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
10a50 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
10a60 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
10a70 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
10a80 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
10a90 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
10aa0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
10ab0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
10ac0 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
10ad0 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
10ae0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
10af0 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
10b00 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
10b10 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
10b20 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
10b30 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
10b40 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
10b50 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51  ontext..**.** SQ
10b60 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
10b70 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
10b80 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
10b90 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
10ba0 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
10bb0 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
10bc0 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
10bd0 20 44 6f 69 6e 67 20 73 6f 20 69 73 20 6d 75 63   Doing so is muc
10be0 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  h faster than go
10bf0 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  ing.** through a
10c00 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69  nd deleting indi
10c10 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20  vidual elements 
10c20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 20  from the table. 
10c30 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73   Because of this
10c40 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  .** optimization
10c50 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20  , the deletions 
10c60 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  in "DELETE FROM 
10c70 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72  table" are not r
10c80 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a  ow changes and.*
10c90 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f  * will not be co
10ca0 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  unted by the sql
10cb0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f  ite3_changes() o
10cc0 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  r [sqlite3_total
10cd0 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66  _changes()].** f
10ce0 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64  unctions, regard
10cf0 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62  less of the numb
10d00 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74  er of elements t
10d10 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61  hat were origina
10d20 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61  lly.** in the ta
10d30 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20  ble.  To get an 
10d40 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f  accurate count o
10d50 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
10d60 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
10d70 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
10d80 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
10d90 20 69 6e 73 74 65 61 64 2e 20 20 4f 72 20 72 65   instead.  Or re
10da0 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67 20 74 68  compile using th
10db0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  e.** [SQLITE_OMI
10dc0 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50 54 49 4d  T_TRUNCATE_OPTIM
10dd0 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70 69 6c 65  IZATION] compile
10de0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 6f 20  -time option to 
10df0 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 6f  disable the.** o
10e00 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f 6e 20 61  ptimization on a
10e10 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  ll queries..**.*
10e20 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
10e30 0a 2a 2a 20 7b 48 31 32 32 34 31 7d 20 54 68 65  .** {H12241} The
10e40 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
10e50 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  s()] function sh
10e60 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 6e  all return the n
10e70 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20  umber of.**     
10e80 20 20 20 20 20 72 6f 77 20 63 68 61 6e 67 65 73       row changes
10e90 20 63 61 75 73 65 64 20 62 79 20 74 68 65 20 6d   caused by the m
10ea0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
10eb0 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20 20  T, UPDATE,.**   
10ec0 20 20 20 20 20 20 20 6f 72 20 44 45 4c 45 54 45         or DELETE
10ed0 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68   statement on th
10ee0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
10ef0 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a 2a  connection and.*
10f00 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 69  *          withi
10f10 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69  n the same or hi
10f20 67 68 65 72 20 74 72 69 67 67 65 72 20 63 6f 6e  gher trigger con
10f30 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66  text, or zero if
10f40 20 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20   there have.**  
10f50 20 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e          not been
10f60 20 61 6e 79 20 71 75 61 6c 69 66 79 69 6e 67 20   any qualifying 
10f70 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
10f80 2a 2a 20 7b 48 31 32 32 34 33 7d 20 53 74 61 74  ** {H12243} Stat
10f90 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  ements of the fo
10fa0 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  rm "DELETE FROM 
10fb0 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20  tablename" with 
10fc0 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57  no.**          W
10fd0 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c  HERE clause shal
10fe0 6c 20 63 61 75 73 65 20 73 75 62 73 65 71 75 65  l cause subseque
10ff0 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20  nt calls to.**  
11000 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
11010 5f 63 68 61 6e 67 65 73 28 29 5d 20 74 6f 20 72  _changes()] to r
11020 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65 67 61  eturn zero, rega
11030 72 64 6c 65 73 73 20 6f 66 20 74 68 65 0a 2a 2a  rdless of the.**
11040 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
11050 20 6f 66 20 72 6f 77 73 20 6f 72 69 67 69 6e 61   of rows origina
11060 6c 6c 79 20 69 6e 20 74 68 65 20 74 61 62 6c 65  lly in the table
11070 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
11080 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32  ONS:.**.** {A122
11090 35 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  52} If a separat
110a0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
110b0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
110c0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
110d0 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
110e0 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
110f0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
11100 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
11110 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
11120 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75  **          is u
11130 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
11140 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
11150 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
11160 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
11170 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
11180 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
11190 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
111a0 64 20 7b 48 31 32 32 36 30 7d 20 3c 53 31 30 36  d {H12260} <S106
111b0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  00>.**.** This f
111c0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
111d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
111e0 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
111f0 20 62 79 20 49 4e 53 45 52 54 2c 0a 2a 2a 20 55   by INSERT,.** U
11200 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
11210 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
11220 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
11230 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
11240 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63 6f  pened..** The co
11250 75 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  unt includes all
11260 20 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c   changes from al
11270 6c 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  l trigger contex
11280 74 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ts.  However,.**
11290 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
112a0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
112b0 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
112c0 65 6d 65 6e 74 20 52 45 50 4c 41 43 45 20 63 6f  ement REPLACE co
112d0 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f  nstraints,.** do
112e0 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
112f0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
11300 6f 72 20 44 52 4f 50 20 74 61 62 6c 65 20 70 72  or DROP table pr
11310 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 65  ocessing..** The
11320 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75   changes are cou
11330 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  nted as soon as 
11340 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
11350 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
11360 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28 77  .** completed (w
11370 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
11380 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73  t handle is pass
11390 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
113a0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
113b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
113c0 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  )])..**.** SQLit
113d0 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  e implements the
113e0 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45   command "DELETE
113f0 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74   FROM table" wit
11400 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61  hout a WHERE cla
11410 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69  use.** by droppi
11420 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e  ng and recreatin
11430 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54  g the table.  (T
11440 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74  his is much fast
11450 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a  er than going.**
11460 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c   through and del
11470 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c  eting individual
11480 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74   elements from t
11490 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61  he table.)  Beca
114a0 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f  use of this.** o
114b0 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65  ptimization, the
114c0 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44   deletions in "D
114d0 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
114e0 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68  " are not row ch
114f0 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c  anges and.** wil
11500 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64  l not be counted
11510 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
11520 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71  changes() or [sq
11530 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
11540 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  ges()].** functi
11550 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20  ons, regardless 
11560 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
11570 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77   elements that w
11580 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  ere originally.*
11590 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20  * in the table. 
115a0 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72   To get an accur
115b0 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65  ate count of the
115c0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
115d0 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20  deleted, use.** 
115e0 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62  "DELETE FROM tab
115f0 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74  le WHERE 1" inst
11600 65 61 64 2e 20 20 20 4f 72 20 72 65 63 6f 6d 70  ead.   Or recomp
11610 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
11620 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52   [SQLITE_OMIT_TR
11630 55 4e 43 41 54 45 5f 4f 50 54 49 4d 49 5a 41 54  UNCATE_OPTIMIZAT
11640 49 4f 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ION] compile-tim
11650 65 20 6f 70 74 69 6f 6e 20 74 6f 20 64 69 73 61  e option to disa
11660 62 6c 65 20 74 68 65 0a 2a 2a 20 6f 70 74 69 6d  ble the.** optim
11670 69 7a 61 74 69 6f 6e 20 6f 6e 20 61 6c 6c 20 71  ization on all q
11680 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 65  ueries..**.** Se
11690 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
116a0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
116b0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
116c0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
116d0 2a 20 7b 48 31 32 32 36 31 7d 20 54 68 65 20 5b  * {H12261} The [
116e0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
116f0 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73  anges()] returns
11700 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
11710 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  r.**          of
11720 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
11730 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55  sed by INSERT, U
11740 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45  PDATE, and/or DE
11750 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20  LETE.**         
11760 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74   statements on t
11770 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
11780 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69  e connection], i
11790 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20  n any.**        
117a0 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78    trigger contex
117b0 74 2c 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  t, since the dat
117c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
117d0 20 77 61 73 20 63 72 65 61 74 65 64 2e 0a 2a 2a   was created..**
117e0 0a 2a 2a 20 7b 48 31 32 32 36 33 7d 20 53 74 61  .** {H12263} Sta
117f0 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66  tements of the f
11800 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  orm "DELETE FROM
11810 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68   tablename" with
11820 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   no.**          
11830 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61  WHERE clause sha
11840 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  ll not change th
11850 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
11860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
11870 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
11880 68 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a  hanges()]..**.**
11890 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
118a0 0a 2a 2a 20 7b 41 31 32 32 36 34 7d 20 49 66 20  .** {A12264} If 
118b0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
118c0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
118d0 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
118e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
118f0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c  **          whil
11900 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
11910 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
11920 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
11930 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20  value.**        
11940 20 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e    returned is un
11950 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
11960 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
11970 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
11980 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
11990 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
119a0 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
119b0 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
119c0 67 20 51 75 65 72 79 20 7b 48 31 32 32 37 30 7d  g Query {H12270}
119d0 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30500>.**.** 
119e0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
119f0 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
11a00 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
11a10 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
11a20 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
11a30 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
11a40 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
11a50 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
11a60 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
11a70 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
11a80 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
11a90 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
11aa0 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
11ab0 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
11ac0 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
11ad0 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
11ae0 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
11af0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ly..**.** It is 
11b00 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
11b10 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
11b20 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
11b30 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
11b40 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
11b50 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
11b60 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
11b70 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
11b80 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
11b90 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
11ba0 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
11bb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11bc0 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
11bd0 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
11be0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
11bf0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
11c00 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  rns..**.** If an
11c10 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
11c20 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
11c30 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
11c40 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
11c50 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
11c60 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
11c70 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
11c80 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
11c90 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
11ca0 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
11cb0 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
11cc0 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  etion..**.** An 
11cd0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
11ce0 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
11cf0 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
11d00 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
11d10 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65  ..** If the inte
11d20 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
11d30 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
11d40 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
11d50 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
11d60 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
11d70 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
11d80 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
11d90 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
11da0 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
11db0 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
11dc0 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  y..**.** A call 
11dd0 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
11de0 72 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66  rupt() has no ef
11df0 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
11e00 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
11e10 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
11e20 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
11e30 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
11e40 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
11e50 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 31 7d 20 54  **.** {H12271} T
11e60 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  he [sqlite3_inte
11e70 72 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61  rrupt()] interfa
11e80 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c  ce will force al
11e90 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20  l running.**    
11ea0 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
11eb0 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
11ec0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61  with the same da
11ed0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11ee0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  n.**          to
11ef0 20 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63   halt after proc
11f00 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f  essing at most o
11f10 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f  ne additional ro
11f20 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
11f30 20 7b 48 31 32 32 37 32 7d 20 41 6e 79 20 53 51   {H12272} Any SQ
11f40 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
11f50 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
11f60 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  by [sqlite3_inte
11f70 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20  rrupt()].**     
11f80 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e       will return
11f90 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
11fa0 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  PT]..**.** ASSUM
11fb0 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
11fc0 31 32 32 37 39 7d 20 49 66 20 74 68 65 20 64 61  12279} If the da
11fd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11fe0 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
11ff0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
12000 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
12010 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
12020 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
12030 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
12040 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
12050 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
12060 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
12070 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
12080 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
12090 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20  ent Is Complete 
120a0 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30  {H10510} <S70200
120b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
120c0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
120d0 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69  l for command-li
120e0 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
120f0 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
12100 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
12110 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
12120 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20  form complete a 
12130 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
12140 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
12150 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
12160 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
12170 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
12180 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
12190 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75  sing.  These rou
121a0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 72 75  tines return tru
121b0 65 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  e if the input s
121c0 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
121d0 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
121e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
121f0 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73    A statement is
12200 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
12210 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
12220 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
12230 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
12240 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e  is not a fragmen
12250 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54 45  t of a.** CREATE
12260 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
12270 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20  nt.  Semicolons 
12280 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
12290 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
122a0 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
122b0 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
122c0 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
122d0 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
122e0 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
122f0 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
12300 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
12310 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
12320 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
12330 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
12340 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
12350 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
12360 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
12370 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
12380 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
12390 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
123a0 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
123b0 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
123c0 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  t SQL..**.** INV
123d0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
123e0 48 31 30 35 31 31 7d 20 41 20 73 75 63 63 65 73  H10511} A succes
123f0 73 66 75 6c 20 65 76 61 6c 75 61 74 69 6f 6e 20  sful evaluation 
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 0a 2a 2a 20 20 20  lete()] or.**   
12420 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
12430 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 66 75  complete16()] fu
12440 6e 63 74 69 6f 6e 73 20 73 68 61 6c 6c 0a 2a 2a  nctions shall.**
12450 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
12460 20 61 20 6e 75 6d 65 72 69 63 20 31 20 69 66 20   a numeric 1 if 
12470 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
12480 6c 61 73 74 20 6e 6f 6e 2d 77 68 69 74 65 73 70  last non-whitesp
12490 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ace.**          
124a0 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20 69  token in their i
124b0 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69 63 6f  nput is a semico
124c0 6c 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20  lon that is not 
124d0 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 20 20  in between.**   
124e0 20 20 20 20 20 20 20 74 68 65 20 42 45 47 49 4e         the BEGIN
124f0 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43 52   and END of a CR
12500 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
12510 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tement..**.** {H
12520 31 30 35 31 32 7d 20 49 66 20 61 20 6d 65 6d 6f  10512} If a memo
12530 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
12540 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
12550 67 20 61 6e 20 69 6e 76 6f 63 61 74 69 6f 6e 0a  g an invocation.
12560 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 5b  **          of [
12570 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
12580 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
12590 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 74 68  complete16()] th
125a0 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
125b0 20 20 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c     routine shall
125c0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
125d0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53  NOMEM]..**.** AS
125e0 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
125f0 20 7b 41 31 30 35 31 32 7d 20 54 68 65 20 69 6e   {A10512} The in
12600 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
12610 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
12620 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
12630 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
12640 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a    UTF-8 string..
12650 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 33 7d 20 54  **.** {A10513} T
12660 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
12670 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
12680 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
12690 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
126a0 20 20 20 20 20 20 20 20 20 55 54 46 2d 31 36 20           UTF-16 
126b0 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
126c0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
126d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
126e0 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
126f0 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
12700 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
12710 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
12720 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12730 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
12740 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
12750 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
12760 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34  s {H12310} <S404
12770 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
12780 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
12790 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
127a0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
127b0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
127c0 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
127d0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
127e0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
127f0 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
12800 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
12810 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
12820 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61  * If the busy ca
12830 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
12840 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
12850 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
12860 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
12870 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
12880 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
12890 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
128a0 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20  ck. If the busy 
128b0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
128c0 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
128d0 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20  e callback will 
128e0 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
128f0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
12900 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
12910 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68  rgument to the h
12920 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
12930 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
12940 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
12950 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
12960 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
12970 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
12980 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
12990 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68  ment to.** the h
129a0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
129b0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
129c0 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
129d0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
129e0 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
129f0 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
12a00 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65  g event.  If the
12a10 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
12a20 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
12a30 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
12a40 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
12a50 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
12a60 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
12a70 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
12a80 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
12a90 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
12aa0 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ned..** If the c
12ab0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
12ac0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
12ad0 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
12ae0 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
12af0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
12b00 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
12b10 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
12b20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
12b30 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
12b40 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
12b50 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
12b60 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
12b70 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
12b80 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
12b90 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65  on. If SQLite de
12ba0 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
12bb0 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
12bc0 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
12bd0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
12be0 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
12bf0 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
12c00 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
12c10 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
12c20 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
12c30 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
12c40 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
12c50 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
12c60 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
12c70 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
12c80 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
12c90 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
12ca0 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
12cb0 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
12cc0 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
12cd0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
12ce0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
12cf0 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
12d00 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
12d10 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
12d20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
12d30 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
12d40 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
12d50 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
12d60 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
12d70 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
12d80 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
12d90 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
12da0 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
12db0 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
12dc0 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
12dd0 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
12de0 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
12df0 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
12e00 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
12e10 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
12e20 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
12e30 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
12e40 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
12e50 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
12e60 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
12e70 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
12e80 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
12e90 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
12ea0 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
12eb0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
12ec0 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
12ed0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
12ee0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
12ef0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  is NULL..**.** T
12f00 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
12f10 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
12f20 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
12f30 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
12f40 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
12f50 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
12f60 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
12f70 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
12f80 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
12f90 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
12fa0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
12fb0 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
12fc0 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
12fd0 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
12fe0 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
12ff0 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
13000 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
13010 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
13020 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
13030 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
13040 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
13050 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
13060 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
13070 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
13080 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20  ** readers.  If 
13090 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
130a0 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
130b0 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
130c0 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
130d0 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
130e0 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
130f0 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
13100 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
13110 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
13120 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
13130 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
13140 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
13150 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
13160 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
13170 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65   This error code
13180 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
13190 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
131a0 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
131b0 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
131c0 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
131d0 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
131e0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
131f0 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
13200 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
13210 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
13220 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
13230 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
13240 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
13250 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
13260 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20   There can only 
13270 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
13280 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
13290 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
132a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
132b0 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
132c0 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
132d0 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
132e0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
132f0 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  dler.  Note that
13300 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
13310 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
13320 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
13330 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
13340 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
13350 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
13360 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
13370 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
13380 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
13390 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
133a0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
133b0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
133c0 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75  handler.  Any su
133d0 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
133e0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
133f0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
13400 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
13410 2a 0a 2a 2a 20 7b 48 31 32 33 31 31 7d 20 54 68  *.** {H12311} Th
13420 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  e [sqlite3_busy_
13430 68 61 6e 64 6c 65 72 28 44 2c 43 2c 41 29 5d 20  handler(D,C,A)] 
13440 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72  function shall r
13450 65 70 6c 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  eplace.**       
13460 20 20 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b     busy callback
13470 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   in the [databas
13480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
13490 77 69 74 68 20 61 20 6e 65 77 0a 2a 2a 20 20 20  with a new.**   
134a0 20 20 20 20 20 20 20 61 20 6e 65 77 20 62 75 73         a new bus
134b0 79 20 68 61 6e 64 6c 65 72 20 43 20 61 6e 64 20  y handler C and 
134c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
134d0 20 70 6f 69 6e 74 65 72 20 41 2e 0a 2a 2a 0a 2a   pointer A..**.*
134e0 2a 20 7b 48 31 32 33 31 32 7d 20 4e 65 77 6c 79  * {H12312} Newly
134f0 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62 61   created [databa
13500 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
13510 73 68 61 6c 6c 20 68 61 76 65 20 61 20 62 75 73  shall have a bus
13520 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61  y.**          ha
13530 6e 64 6c 65 72 20 6f 66 20 4e 55 4c 4c 2e 0a 2a  ndler of NULL..*
13540 2a 0a 2a 2a 20 7b 48 31 32 33 31 34 7d 20 57 68  *.** {H12314} Wh
13550 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 5b  en two or more [
13560 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13570 69 6f 6e 73 5d 20 73 68 61 72 65 20 61 0a 2a 2a  ions] share a.**
13580 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
13590 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
135a0 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e 20  _cache | common 
135b0 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20 20  cache],.**      
135c0 20 20 20 20 74 68 65 20 62 75 73 79 20 68 61 6e      the busy han
135d0 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61 74  dler for the dat
135e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
135f0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
13600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
13610 20 63 61 63 68 65 20 73 68 61 6c 6c 20 62 65 20   cache shall be 
13620 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
13630 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65 72   cache encounter
13640 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20  s a lock..**.** 
13650 7b 48 31 32 33 31 36 7d 20 49 66 20 61 20 62 75  {H12316} If a bu
13660 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
13670 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ack returns zero
13680 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69 74  , then the SQLit
13690 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20  e interface.**  
136a0 20 20 20 20 20 20 20 20 74 68 61 74 20 70 72 6f          that pro
136b0 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e  voked the lockin
136c0 67 20 65 76 65 6e 74 20 73 68 61 6c 6c 20 72 65  g event shall re
136d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
136e0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31  Y]..**.** {H1231
136f0 38 7d 20 53 51 4c 69 74 65 20 73 68 61 6c 6c 20  8} SQLite shall 
13700 69 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79  invokes the busy
13710 20 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77   handler with tw
13720 6f 20 61 72 67 75 6d 65 6e 74 73 20 77 68 69 63  o arguments whic
13730 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  h.**          ar
13740 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  e a copy of the 
13750 70 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65 64  pointer supplied
13760 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61   by the 3rd para
13770 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20  meter to.**     
13780 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75       [sqlite3_bu
13790 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e  sy_handler()] an
137a0 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68 65  d a count of the
137b0 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72   number of prior
137c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76  .**          inv
137d0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
137e0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
137f0 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
13800 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41  g event..**.** A
13810 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
13820 2a 20 7b 41 31 32 33 31 39 7d 20 41 20 62 75 73  * {A12319} A bus
13830 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
13840 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
13850 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
13870 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13880 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
13890 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
138a0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
138b0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
138c0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
138d0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
138e0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
138f0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
13900 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30   Timeout {H12340
13910 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a  } <S40410>.**.**
13920 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65   This routine se
13930 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
13940 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
13950 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
13960 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
13970 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
13980 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
13990 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
139a0 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a    The handler.**
139b0 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
139c0 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
139d0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
139e0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
139f0 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
13a00 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31  accumulated. {H1
13a10 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22  2343} After "ms"
13a20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
13a30 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
13a40 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
13a50 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
13a60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
13a70 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
13a80 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
13a90 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
13aa0 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61  OCKED]..**.** Ca
13ab0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
13ac0 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
13ad0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
13ae0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
13af0 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
13b00 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
13b10 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f  *.** There can o
13b20 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
13b30 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
13b40 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
13b50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13b60 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
13b70 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
13b80 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
13b90 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
13ba0 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
13bb0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
13bc0 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
13bd0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
13be0 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
13bf0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
13c00 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a   is cleared..**.
13c10 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
13c20 2a 0a 2a 2a 20 7b 48 31 32 33 34 31 7d 20 54 68  *.** {H12341} Th
13c30 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  e [sqlite3_busy_
13c40 74 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63 74  timeout()] funct
13c50 69 6f 6e 20 73 68 61 6c 6c 20 6f 76 65 72 72 69  ion shall overri
13c60 64 65 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20  de any prior.** 
13c70 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
13c80 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
13c90 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75  ] or [sqlite3_bu
13ca0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65  sy_handler()] se
13cb0 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tting.**        
13cc0 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64    on the same [d
13cd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13ce0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  on]..**.** {H123
13cf0 34 33 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70  43} If the 2nd p
13d00 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
13d10 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
13d20 74 28 29 5d 20 69 73 20 6c 65 73 73 20 74 68 61  t()] is less tha
13d30 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
13d40 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20   equal to zero, 
13d50 74 68 65 6e 20 74 68 65 20 62 75 73 79 20 68 61  then the busy ha
13d60 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 63  ndler shall be c
13d70 6c 65 61 72 65 64 20 73 6f 20 74 68 61 74 0a 2a  leared so that.*
13d80 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20 73  *          all s
13d90 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e  ubsequent lockin
13da0 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69 61  g events immedia
13db0 74 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51 4c  tely return [SQL
13dc0 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a  ITE_BUSY]..**.**
13dd0 20 7b 48 31 32 33 34 34 7d 20 49 66 20 74 68 65   {H12344} If the
13de0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
13df0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  o [sqlite3_busy_
13e00 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 61 20  timeout()] is a 
13e10 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20  positive.**     
13e20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74       number N, t
13e30 68 65 6e 20 61 20 62 75 73 79 20 68 61 6e 64 6c  hen a busy handl
13e40 65 72 20 73 68 61 6c 6c 20 62 65 20 73 65 74 20  er shall be set 
13e50 74 68 61 74 20 72 65 70 65 61 74 65 64 6c 79 20  that repeatedly 
13e60 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20  calls.**        
13e70 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d    the xSleep() m
13e80 65 74 68 6f 64 20 69 6e 20 74 68 65 20 5b 73 71  ethod in the [sq
13e90 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 20  lite3_vfs | VFS 
13ea0 69 6e 74 65 72 66 61 63 65 5d 20 75 6e 74 69 6c  interface] until
13eb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 69 74  .**          eit
13ec0 68 65 72 20 74 68 65 20 6c 6f 63 6b 20 63 6c 65  her the lock cle
13ed0 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ars or until the
13ee0 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65 65   cumulative slee
13ef0 70 20 74 69 6d 65 0a 2a 2a 20 20 20 20 20 20 20  p time.**       
13f00 20 20 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b     reported back
13f10 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 78 63   by xSleep() exc
13f20 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f  eeds N milliseco
13f30 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nds..*/.int sqli
13f40 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
13f50 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
13f60 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
13f70 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
13f80 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
13f90 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b 48  nning Queries {H
13fa0 31 32 33 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a  12370} <S10000>.
13fb0 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
13fc0 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
13fd0 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
13fe0 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
13ff0 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
14000 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
14010 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
14020 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
14030 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
14040 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
14050 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
14060 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
14070 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
14080 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
14090 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
140a0 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
140b0 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
140c0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
140d0 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
140e0 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
140f0 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
14100 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
14110 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
14120 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
14130 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
14140 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
14150 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
14160 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
14170 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
14180 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
14190 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
141a0 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
141b0 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
141c0 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
141d0 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
141e0 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
141f0 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
14200 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
14210 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
14220 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
14230 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
14240 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
14250 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
14260 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
14270 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
14280 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
14290 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
142a0 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
142b0 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
142c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
142d0 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
142e0 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
142f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
14300 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
14310 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
14320 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
14330 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
14340 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14350 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
14360 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
14370 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
14380 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
14390 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
143a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
143b0 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
143c0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
143d0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
143e0 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61  .**.** As an exa
143f0 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
14400 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
14410 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
14420 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
14430 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
14440 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
14450 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
14460 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
14470 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
14480 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
14490 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
144a0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
144b0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
144c0 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
144d0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
144e0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
144f0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
14500 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
14510 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
14520 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
14530 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
14540 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
14550 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
14560 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
14570 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
14580 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
14590 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
145a0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
145b0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
145c0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
145d0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
145e0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
145f0 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
14600 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
14610 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
14620 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
14630 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
14640 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
14650 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
14660 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
14670 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
14680 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
14690 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
146a0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
146b0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
146c0 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
146d0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
146e0 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
146f0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
14700 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
14710 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
14720 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
14730 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
14740 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
14750 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
14760 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
14770 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
14780 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
14790 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
147a0 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74  rameter.  It ret
147b0 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
147c0 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
147d0 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
147e0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
147f0 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
14800 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
14810 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
14820 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  using the result
14830 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70  , it should.** p
14840 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20  ass the pointer 
14850 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  to the result ta
14860 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ble to sqlite3_f
14870 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
14880 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
14890 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
148a0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
148b0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
148c0 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
148d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
148e0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
148f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14900 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
14910 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
14920 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
14930 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
14940 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
14950 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
14960 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
14970 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
14980 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
14990 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
149a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
149b0 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
149c0 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
149d0 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
149e0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
149f0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
14a00 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
14a10 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
14a20 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
14a30 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
14a40 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
14a50 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
14a60 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
14a70 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
14a80 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
14a90 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
14aa0 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
14ab0 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
14ac0 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
14ad0 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
14ae0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
14af0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
14b00 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
14b10 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
14b20 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
14b30 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
14b40 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
14b50 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  msg()]..**.** IN
14b60 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
14b70 7b 48 31 32 33 37 31 7d 20 49 66 20 61 20 5b 73  {H12371} If a [s
14b80 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14b90 28 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f  ()] fails a memo
14ba0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  ry allocation, t
14bb0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
14bc0 69 74 20 73 68 61 6c 6c 20 66 72 65 65 20 74 68  it shall free th
14bd0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75  e result table u
14be0 6e 64 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f  nder constructio
14bf0 6e 2c 20 61 62 6f 72 74 20 74 68 65 0a 2a 2a 20  n, abort the.** 
14c00 20 20 20 20 20 20 20 20 20 71 75 65 72 79 20 69           query i
14c10 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70 20  n process, skip 
14c20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 71  any subsequent q
14c30 75 65 72 69 65 73 2c 20 73 65 74 20 74 68 65 0a  ueries, set the.
14c40 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 70 61 7a  **          *paz
14c50 52 65 73 75 6c 74 20 6f 75 74 70 75 74 20 70 6f  Result output po
14c60 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e  inter to NULL an
14c70 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
14c80 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  _NOMEM]..**.** {
14c90 48 31 32 33 37 33 7d 20 49 66 20 74 68 65 20 70  H12373} If the p
14ca0 6e 43 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65  nColumn paramete
14cb0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65  r to [sqlite3_ge
14cc0 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f  t_table()] is no
14cd0 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  t NULL.**       
14ce0 20 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73     then a succes
14cf0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
14d00 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  of [sqlite3_get_
14d10 74 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a  table()] shall.*
14d20 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65  *          write
14d30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
14d40 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
14d50 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74            result
14d60 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72   set of the quer
14d70 79 20 69 6e 74 6f 20 2a 70 6e 43 6f 6c 75 6d 6e  y into *pnColumn
14d80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 34 7d  ..**.** {H12374}
14d90 20 49 66 20 74 68 65 20 70 6e 52 6f 77 20 70 61   If the pnRow pa
14da0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
14db0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
14dc0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20   is not NULL.** 
14dd0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 61 20           then a 
14de0 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
14df0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
14e00 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73  3_get_table()] s
14e10 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
14e20 20 77 72 69 74 65 73 20 74 68 65 20 6e 75 6d 62   writes the numb
14e30 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68  er of rows in th
14e40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
14e50 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20  sult set of the 
14e60 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 52 6f  query into *pnRo
14e70 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 36  w..**.** {H12376
14e80 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
14e90 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
14ea0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14eb0 29 5d 20 74 68 61 74 20 63 6f 6d 70 75 74 65 73  )] that computes
14ec0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20 72  .**          N r
14ed0 6f 77 73 20 6f 66 20 72 65 73 75 6c 74 20 77 69  ows of result wi
14ee0 74 68 20 43 20 63 6f 6c 75 6d 6e 73 20 70 65 72  th C columns per
14ef0 20 72 6f 77 20 73 68 61 6c 6c 20 6d 61 6b 65 20   row shall make 
14f00 2a 70 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 20 20  *pazResult.**   
14f10 20 20 20 20 20 20 20 70 6f 69 6e 74 20 74 6f 20         point to 
14f20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
14f30 74 65 72 73 20 74 6f 20 28 4e 2b 31 29 2a 43 20  ters to (N+1)*C 
14f40 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 74 68  strings where th
14f50 65 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  e first.**      
14f60 20 20 20 20 43 20 73 74 72 69 6e 67 73 20 61 72      C strings ar
14f70 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61  e column names a
14f80 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  s obtained from.
14f90 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
14fa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
14fb0 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 74  ()] and the rest
14fc0 20 61 72 65 20 63 6f 6c 75 6d 6e 20 72 65 73 75   are column resu
14fd0 6c 74 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  lt values.**    
14fe0 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66        obtained f
14ff0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
15000 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
15010 2a 2a 20 7b 48 31 32 33 37 39 7d 20 54 68 65 20  ** {H12379} The 
15020 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 70 61  values in the pa
15030 7a 52 65 73 75 6c 74 20 61 72 72 61 79 20 72 65  zResult array re
15040 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
15050 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a  e3_get_table()].
15060 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
15070 6c 20 72 65 6d 61 69 6e 20 76 61 6c 69 64 20 75  l remain valid u
15080 6e 74 69 6c 20 63 6c 65 61 72 65 64 20 62 79 20  ntil cleared by 
15090 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
150a0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ble()]..**.** {H
150b0 31 32 33 38 32 7d 20 57 68 65 6e 20 61 6e 20 65  12382} When an e
150c0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
150d0 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  ng evaluation of
150e0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
150f0 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ble()].**       
15100 20 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20     the function 
15110 73 68 61 6c 6c 20 73 65 74 20 2a 70 61 7a 52 65  shall set *pazRe
15120 73 75 6c 74 20 74 6f 20 4e 55 4c 4c 2c 20 77 72  sult to NULL, wr
15130 69 74 65 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ite an error mes
15140 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  sage.**         
15150 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
15160 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
15170 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 6d  te3_malloc()], m
15180 61 6b 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ake.**          
15190 2a 2a 70 7a 45 72 72 6d 73 67 20 70 6f 69 6e 74  **pzErrmsg point
151a0 20 74 6f 20 74 68 61 74 20 65 72 72 6f 72 20 6d   to that error m
151b0 65 73 73 61 67 65 2c 20 61 6e 64 20 72 65 74 75  essage, and retu
151c0 72 6e 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  rn a.**         
151d0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
151e0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e  ror code]..*/.in
151f0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
15200 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
15210 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
15220 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
15230 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
15240 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
15250 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
15260 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
15270 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
15280 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
15290 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
152a0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
152b0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
152c0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
152d0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
152e0 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
152f0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
15300 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
15310 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
15320 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
15330 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
15340 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
15350 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
15360 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
15370 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
15380 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
15390 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
153a0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
153b0 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c 53 37 30  ns {H17400} <S70
153c0 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  000><S20000>.**.
153d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
153e0 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73  s are workalikes
153f0 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
15400 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
15410 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
15420 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
15430 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  brary..**.** The
15440 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
15450 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
15460 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
15470 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
15480 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
15490 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
154a0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
154b0 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
154c0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
154d0 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
154e0 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
154f0 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
15500 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
15510 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20    Both routines 
15520 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
15530 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
15540 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
15550 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
15560 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
15570 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
15580 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
15590 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c  ng..**.** In sql
155a0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
155b0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
155c0 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
155d0 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
155e0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
155f0 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
15600 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
15610 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
15620 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
15630 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
15640 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
15650 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
15660 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
15670 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
15680 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
15690 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
156a0 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
156b0 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68   snprintf().  Th
156c0 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
156d0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
156e0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
156f0 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
15700 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
15710 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
15720 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61  .  Note also tha
15730 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
15740 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
15750 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
15760 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
15770 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
15780 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
15790 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
157a0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
157b0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
157c0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
157d0 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
157e0 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
157f0 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
15800 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
15810 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
15820 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
15830 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
15840 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
15850 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
15860 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
15870 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73  **.** As long as
15880 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
15890 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
158a0 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
158b0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
158c0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
158d0 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
158e0 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
158f0 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  d.  The first.**
15900 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
15910 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
15920 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
15930 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
15940 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
15950 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
15960 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
15970 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
15980 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
15990 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
159a0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
159b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
159c0 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
159d0 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
159e0 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
159f0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
15a00 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
15a10 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
15a20 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
15a30 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
15a40 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
15a50 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
15a60 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
15a70 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
15a80 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22  , "%Q", and "%z"
15a90 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   options..**.** 
15aa0 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
15ab0 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
15ac0 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
15ad0 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e  es a null-termin
15ae0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
15af0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
15b00 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
15b10 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
15b20 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
15b30 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
15b40 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
15b50 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
15b60 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e  ral.  By doublin
15b70 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
15b80 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
15b90 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
15ba0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
15bb0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
15bc0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
15bd0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
15be0 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
15bf0 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
15c00 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
15c10 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
15c20 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
15c30 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
15c40 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
15c50 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
15c60 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
15c70 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
15c80 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
15c90 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
15ca0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
15cb0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
15cc0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
15cd0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
15ce0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
15cf0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
15d00 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
15d10 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
15d20 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
15d30 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
15d40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
15d50 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
15d60 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
15d70 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
15d80 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
15d90 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
15da0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
15db0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
15dc0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
15dd0 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
15de0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
15df0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
15e00 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
15e10 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
15e20 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
15e30 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
15e40 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
15e50 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
15e60 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
15e70 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
15e80 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
15e90 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
15ea0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
15eb0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
15ec0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
15ed0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
15ee0 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
15ef0 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
15f00 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
15f10 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
15f20 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
15f30 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
15f40 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
15f50 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
15f60 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
15f70 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
15f80 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
15f90 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
15fa0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
15fb0 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f  .** The %Q optio
15fc0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
15fd0 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
15fe0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
15ff0 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
16000 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
16010 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
16020 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
16030 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
16040 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
16050 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
16060 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
16070 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
16080 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
16090 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
160a0 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  ) in place of th
160b0 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f  e %Q option.  So
160c0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
160d0 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
160e0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
160f0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
16100 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
16110 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
16120 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
16130 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
16140 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
16150 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
16160 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
16170 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
16180 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
16190 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
161a0 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
161b0 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
161c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
161d0 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
161e0 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
161f0 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
16200 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
16210 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22  ..**.** The "%z"
16220 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
16230 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79  on works exactly
16240 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20   like "%s" with 
16250 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
16260 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
16270 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
16280 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
16290 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
162a0 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
162b0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
162c0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
162d0 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49  g. {END}.**.** I
162e0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
162f0 20 7b 48 31 37 34 30 33 7d 20 20 54 68 65 20 5b   {H17403}  The [
16300 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
16310 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
16320 76 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  vmprintf()] inte
16330 72 66 61 63 65 73 0a 2a 2a 20 20 20 20 20 20 20  rfaces.**       
16340 20 20 20 20 72 65 74 75 72 6e 20 65 69 74 68 65      return eithe
16350 72 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  r pointers to ze
16360 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
16370 46 2d 38 20 73 74 72 69 6e 67 73 20 68 65 6c 64  F-8 strings held
16380 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   in.**          
16390 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
163a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
163b0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c 4c  alloc()] or NULL
163c0 20 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a 20   pointers if.** 
163d0 20 20 20 20 20 20 20 20 20 20 61 20 63 61 6c 6c            a call
163e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
163f0 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a  loc()] fails..**
16400 0a 2a 2a 20 7b 48 31 37 34 30 36 7d 20 20 54 68  .** {H17406}  Th
16410 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  e [sqlite3_snpri
16420 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ntf()] interface
16430 20 77 72 69 74 65 73 20 61 20 7a 65 72 6f 2d 74   writes a zero-t
16440 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20  erminated.**    
16450 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
16460 69 6e 67 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ing into the buf
16470 66 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  fer pointed to b
16480 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
16490 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  ameter.**       
164a0 20 20 20 20 70 72 6f 76 69 64 65 64 20 74 68 61      provided tha
164b0 74 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  t the first para
164c0 6d 65 74 65 72 20 69 73 20 67 72 65 61 74 65 72  meter is greater
164d0 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a   than zero..**.*
164e0 2a 20 7b 48 31 37 34 30 37 7d 20 20 54 68 65 20  * {H17407}  The 
164f0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
16500 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  f()] interface d
16510 6f 65 73 20 6e 6f 74 20 77 72 69 74 65 20 73 6c  oes not write sl
16520 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ots of.**       
16530 20 20 20 20 69 74 73 20 6f 75 74 70 75 74 20 62      its output b
16540 75 66 66 65 72 20 28 74 68 65 20 73 65 63 6f 6e  uffer (the secon
16550 64 20 70 61 72 61 6d 65 74 65 72 29 20 6f 75 74  d parameter) out
16560 73 69 64 65 20 74 68 65 20 72 61 6e 67 65 0a 2a  side the range.*
16570 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 20 30  *           of 0
16580 20 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 77 68   through N-1 (wh
16590 65 72 65 20 4e 20 69 73 20 74 68 65 20 66 69 72  ere N is the fir
165a0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
165b0 20 20 20 20 20 20 20 20 20 20 20 72 65 67 61 72             regar
165c0 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6c 65 6e  dless of the len
165d0 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
165e0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  g.**           r
165f0 65 71 75 65 73 74 65 64 20 62 79 20 74 68 65 20  equested by the 
16600 66 6f 72 6d 61 74 20 73 70 65 63 69 66 69 63 61  format specifica
16610 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73  tion..*/.char *s
16620 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
16630 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
16640 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
16650 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
16660 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
16670 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
16680 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
16690 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
166a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
166b0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
166c0 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20  ation Subsystem 
166d0 7b 48 31 37 33 30 30 7d 20 3c 53 32 30 30 30 30  {H17300} <S20000
166e0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  >.**.** The SQLi
166f0 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 74 68  te core  uses th
16700 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
16710 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
16720 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
16730 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
16740 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
16750 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
16760 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
16770 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
16780 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
16790 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
167a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
167b0 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
167c0 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
167d0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
167e0 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
167f0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
16800 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16810 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
16820 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
16830 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
16840 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
16850 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
16860 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
16870 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73  rameter..** If s
16880 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
16890 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
168a0 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
168b0 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
168c0 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
168d0 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68   pointer.  If th
168e0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
168f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
16900 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
16910 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
16920 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
16930 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
16940 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
16950 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
16960 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
16970 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
16980 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
16990 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
169a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
169b0 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
169c0 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
169d0 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
169e0 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 20 73  e reused.  The s
169f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
16a00 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
16a10 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
16a20 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
16a30 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
16a40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
16a50 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
16a60 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
16a70 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
16a80 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
16a90 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
16aa0 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
16ab0 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
16ac0 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
16ad0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
16ae0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
16af0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
16b00 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
16b10 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
16b20 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
16b30 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
16b40 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
16b50 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
16b60 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
16b70 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
16b80 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
16b90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
16ba0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
16bb0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
16bc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
16bd0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16be0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
16bf0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
16c00 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
16c10 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
16c20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
16c30 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
16c40 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
16c50 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
16c60 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
16c70 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
16c80 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
16c90 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
16ca0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
16cb0 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 72 73  er.  If the firs
16cc0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
16cd0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16ce0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
16cf0 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
16d00 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
16d10 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
16d20 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
16d30 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
16d40 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
16d50 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
16d60 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66  realloc()..** If
16d70 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
16d80 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
16d90 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
16da0 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
16db0 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
16dc0 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
16dd0 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
16de0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
16df0 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
16e00 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
16e10 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
16e20 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71  realloc()..** sq
16e30 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
16e40 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
16e50 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
16e60 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
16e70 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
16e80 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
16e90 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  if sufficient me
16ea0 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61  mory is unavaila
16eb0 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20  ble..** If M is 
16ec0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
16ed0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
16ee0 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
16ef0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
16f00 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
16f10 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
16f20 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
16f30 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
16f40 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
16f50 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
16f60 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
16f70 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
16f80 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
16f90 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  oc() returns NUL
16fa0 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f  L, then the prio
16fb0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  r allocation.** 
16fc0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
16fd0 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72  .** The memory r
16fe0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
16ff0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
17000 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17010 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
17020 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
17030 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
17040 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ndary. {END}.**.
17050 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 69  ** The default i
17060 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
17070 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
17080 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
17090 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c   uses.** the mal
170a0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
170b0 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76   and free() prov
170c0 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61 6e  ided by the stan
170d0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
170e0 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 65  ** {H17382} Howe
170f0 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
17100 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
17110 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45  the.** SQLITE_ME
17120 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e  MORY_SIZE=<i>NNN
17130 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73  </i> C preproces
17140 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65  sor macro (where
17150 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69   <i>NNN</i>.** i
17160 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74  s an integer), t
17170 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74  hen SQLite creat
17180 65 20 61 20 73 74 61 74 69 63 20 61 72 72 61 79  e a static array
17190 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20   of at least.** 
171a0 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73  <i>NNN</i> bytes
171b0 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65   in size and use
171c0 73 20 74 68 61 74 20 61 72 72 61 79 20 66 6f 72  s that array for
171d0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
171e0 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  mic.** memory al
171f0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
17200 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61  {END}  Additiona
17210 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
17220 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61  or options.** ma
17230 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
17240 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
17250 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
17260 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
17270 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
17280 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
17290 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
172a0 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
172b0 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
172c0 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
172d0 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
172e0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
172f0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
17300 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
17310 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
17320 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
17330 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
17340 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
17350 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
17360 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64  ..**.** The Wind
17370 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
17380 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
17390 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
173a0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
173b0 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
173c0 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
173d0 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
173e0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
173f0 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
17400 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
17410 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
17420 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
17430 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
17440 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
17450 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
17460 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
17470 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
17480 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
17490 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
174a0 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
174b0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
174c0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
174d0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
174e0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
174f0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 33 7d  :.**.** {H17303}
17500 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
17510 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66  alloc(N)] interf
17520 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
17530 65 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  er a pointer to.
17540 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 6e  **           a n
17550 65 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75 74  ewly checked-out
17560 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61   block of at lea
17570 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  st N bytes of me
17580 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  mory.**         
17590 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65    that is 8-byte
175a0 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 69 74 20   aligned, or it 
175b0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
175c0 69 74 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20  it is unable.** 
175d0 20 20 20 20 20 20 20 20 20 20 74 6f 20 66 75 6c            to ful
175e0 66 69 6c 6c 20 74 68 65 20 72 65 71 75 65 73 74  fill the request
175f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 34 7d  ..**.** {H17304}
17600 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
17610 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66  alloc(N)] interf
17620 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ace returns a NU
17630 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a  LL pointer if.**
17640 20 20 20 20 20 20 20 20 20 20 20 4e 20 69 73 20             N is 
17650 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
17660 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  al to zero..**.*
17670 2a 20 7b 48 31 37 33 30 35 7d 20 20 54 68 65 20  * {H17305}  The 
17680 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29  [sqlite3_free(P)
17690 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 6c 65  ] interface rele
176a0 61 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 65 76  ases memory prev
176b0 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20  iously.**       
176c0 20 20 20 20 72 65 74 75 72 6e 65 64 20 66 72 6f      returned fro
176d0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
176e0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
176f0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  _realloc()],.** 
17700 20 20 20 20 20 20 20 20 20 20 6d 61 6b 69 6e 67            making
17710 20 69 74 20 61 76 61 69 6c 61 62 6c 65 20 66 6f   it available fo
17720 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b  r reuse..**.** {
17730 48 31 37 33 30 36 7d 20 20 41 20 63 61 6c 6c 20  H17306}  A call 
17740 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
17750 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 61 72  (NULL)] is a har
17760 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
17770 2a 2a 20 7b 48 31 37 33 31 30 7d 20 20 41 20 63  ** {H17310}  A c
17780 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
17790 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73  realloc(0,N)] is
177a0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61   equivalent to a
177b0 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20   call.**        
177c0 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d     to [sqlite3_m
177d0 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  alloc(N)]..**.**
177e0 20 7b 48 31 37 33 31 32 7d 20 20 41 20 63 61 6c   {H17312}  A cal
177f0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
17800 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20 65  alloc(P,0)] is e
17810 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63  quivalent to a c
17820 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
17830 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
17840 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  e(P)]..**.** {H1
17850 37 33 31 35 7d 20 20 54 68 65 20 53 51 4c 69 74  7315}  The SQLit
17860 65 20 63 6f 72 65 20 75 73 65 73 20 5b 73 71 6c  e core uses [sql
17870 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
17880 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
17890 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
178a0 20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66    and [sqlite3_f
178b0 72 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f  ree()] for all o
178c0 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  f its memory all
178d0 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20  ocation and.**  
178e0 20 20 20 20 20 20 20 20 20 64 65 61 6c 6c 6f 63           dealloc
178f0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  ation needs..**.
17900 2a 2a 20 7b 48 31 37 33 31 38 7d 20 20 54 68 65  ** {H17318}  The
17910 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
17920 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  c(P,N)] interfac
17930 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
17940 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
17950 20 20 20 20 20 20 20 20 74 6f 20 61 20 62 6c 6f          to a blo
17960 63 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75  ck of checked-ou
17970 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c  t memory of at l
17980 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
17990 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  size.**         
179a0 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65    that is 8-byte
179b0 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e   aligned, or a N
179c0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
179d0 2a 2a 20 7b 48 31 37 33 32 31 7d 20 20 57 68 65  ** {H17321}  Whe
179e0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  n [sqlite3_reall
179f0 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73  oc(P,N)] returns
17a00 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
17a10 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a  ter, it first.**
17a20 20 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65             copie
17a30 73 20 74 68 65 20 66 69 72 73 74 20 4b 20 62 79  s the first K by
17a40 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66  tes of content f
17a50 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 20 6e  rom P into the n
17a60 65 77 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ewly.**         
17a70 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 6c 6f 63    allocated bloc
17a80 6b 2c 20 77 68 65 72 65 20 4b 20 69 73 20 74 68  k, where K is th
17a90 65 20 6c 65 73 73 65 72 20 6f 66 20 4e 20 61 6e  e lesser of N an
17aa0 64 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  d the size of.**
17ab0 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62             the b
17ac0 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b  uffer P..**.** {
17ad0 48 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b 73  H17322}  When [s
17ae0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50  qlite3_realloc(P
17af0 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e  ,N)] returns a n
17b00 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
17b10 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20   it first.**    
17b20 20 20 20 20 20 20 20 72 65 6c 65 61 73 65 73 20         releases 
17b30 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  the buffer P..**
17b40 0a 2a 2a 20 7b 48 31 37 33 32 33 7d 20 20 57 68  .** {H17323}  Wh
17b50 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
17b60 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
17b70 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 66  s NULL, the buff
17b80 65 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20  er P is.**      
17b90 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65       not modifie
17ba0 64 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a  d or released..*
17bb0 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
17bc0 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 30 7d  :.**.** {A17350}
17bd0 20 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72    The pointer ar
17be0 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
17bf0 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
17c00 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
17c10 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
17c20 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
17c30 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
17c40 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
17c50 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20  rom a prior.**  
17c60 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74           invocat
17c70 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
17c80 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
17c90 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
17ca0 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 20 20   that have.**   
17cb0 20 20 20 20 20 20 20 20 6e 6f 74 20 79 65 74 20          not yet 
17cc0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
17cd0 2a 0a 2a 2a 20 7b 41 31 37 33 35 31 7d 20 20 54  *.** {A17351}  T
17ce0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
17cf0 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
17d00 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
17d10 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  f.**           a
17d20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
17d30 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
17d40 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
17d50 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  g.**           [
17d60 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
17d70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
17d80 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
17d90 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
17da0 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
17db0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
17dc0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
17dd0 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
17de0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17df0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
17e00 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20  ator Statistics 
17e10 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30  {H17370} <S30210
17e20 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  >.**.** SQLite p
17e30 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
17e40 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
17e50 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
17e60 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
17e70 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
17e80 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
17e90 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
17ea0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
17eb0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
17ec0 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
17ed0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
17ee0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
17ef0 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  m..**.** INVARIA
17f00 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  NTS:.**.** {H173
17f10 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  71} The [sqlite3
17f20 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
17f30 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
17f40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
17f50 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
17f60 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
17f70 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
17f80 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
17f90 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20  t freed)..**.** 
17fa0 7b 48 31 37 33 37 33 7d 20 54 68 65 20 5b 73 71  {H17373} The [sq
17fb0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
17fc0 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
17fd0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
17fe0 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20  ximum.**        
17ff0 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69    value of [sqli
18000 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
18010 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
18020 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
18030 20 20 20 20 20 20 20 20 20 77 61 73 20 6c 61 73           was las
18040 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b  t reset..**.** {
18050 48 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c 75  H17374} The valu
18060 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
18070 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
18080 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  sed()] and.**   
18090 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
180a0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
180b0 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
180c0 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 20  overhead.**     
180d0 20 20 20 20 20 61 64 64 65 64 20 62 79 20 53 51       added by SQ
180e0 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
180f0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
18100 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18110 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75  ,.**          bu
18120 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61  t not overhead a
18130 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20  dded by the any 
18140 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65  underlying syste
18150 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 20  m library.**    
18160 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20 74        routines t
18170 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
18180 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
18190 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 35 7d 20  .**.** {H17375} 
181a0 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
181b0 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
181c0 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
181d0 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20  nt value of.**  
181e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
181f0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
18200 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
18210 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
18220 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
18230 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
18240 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
18250 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74  .  The value ret
18260 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
18270 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65    by [sqlite3_me
18280 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
18290 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
182a0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20  ater mark.**    
182b0 20 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74        prior to t
182c0 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
182d0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
182e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
182f0 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
18300 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
18310 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
18320 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
18330 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
18340 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
18350 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 48 31  er Generator {H1
18360 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  7390} <S20000>.*
18370 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
18380 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
18390 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
183a0 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
183b0 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
183c0 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
183d0 6f 6d 20 52 4f 57 49 44 73 20 77 68 65 6e 20 69  om ROWIDs when i
183e0 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
183f0 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
18400 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
18410 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
18420 73 74 20 70 6f 73 73 69 62 6c 65 20 52 4f 57 49  st possible ROWI
18430 44 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  D.  The PRNG is 
18440 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
18450 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
18460 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
18470 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
18480 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
18490 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
184a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
184b0 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
184c0 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
184d0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
184e0 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
184f0 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
18500 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
18510 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
18520 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  P..**.** The fir
18530 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
18540 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
18550 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
18560 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
18570 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
18580 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
18590 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
185a0 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
185b0 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
185c0 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
185d0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
185e0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
185f0 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65   On all subseque
18600 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20  nt invocations, 
18610 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
18620 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
18630 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
18640 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
18650 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
18660 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
18670 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
18680 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
18690 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 39  TS:.**.** {H1739
186a0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
186b0 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d  randomness(N,P)]
186c0 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65   interface write
186d0 73 20 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20  s N bytes of.** 
186e0 20 20 20 20 20 20 20 20 20 68 69 67 68 2d 71 75           high-qu
186f0 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
18700 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
18710 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fer P..*/.void s
18720 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
18730 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
18740 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18750 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
18760 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
18770 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30  allbacks {H12500
18780 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70100>.**.**
18790 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
187a0 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72  gisters a author
187b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
187c0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
187d0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
187e0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
187f0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
18800 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
18810 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18820 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
18830 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
18840 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
18850 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
18860 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
18870 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
18880 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
18890 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
188a0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
188b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
188c0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41  pare16_v2()].  A
188d0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
188e0 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
188f0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
18900 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
18910 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
18920 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
18930 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
18940 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18950 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
18960 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
18970 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
18980 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74  llowed.  The aut
18990 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
189a0 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
189b0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
189c0 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
189d0 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
189e0 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
189f0 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
18a00 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
18a10 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
18a20 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
18a30 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
18a40 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
18a50 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
18a60 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
18a70 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
18a80 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
18a90 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75 74  ror.  If the aut
18aa0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18ab0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
18ac0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
18ad0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
18ae0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
18af0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
18b00 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
18b10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
18b20 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
18b30 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
18b40 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
18b50 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
18b60 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
18b70 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
18b80 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
18b90 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
18ba0 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
18bb0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
18bc0 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
18bd0 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  .  When the call
18be0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
18bf0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
18c00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
18c10 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
18c20 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
18c30 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
18c40 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
18c50 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
18c60 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
18c70 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
18c80 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
18c90 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f  d.  If the autho
18ca0 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53  rizer code is [S
18cb0 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
18cc0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
18cd0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
18ce0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
18cf0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
18d00 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
18d10 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
18d20 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
18d30 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
18d40 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
18d50 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
18d60 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
18d70 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
18d80 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
18d90 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
18da0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
18db0 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
18dc0 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
18dd0 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
18de0 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
18df0 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
18e00 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a   of a table..**.
18e10 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
18e20 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
18e30 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18e40 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
18e50 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
18e60 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
18e70 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
18e80 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
18e90 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18ea0 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
18eb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
18ec0 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
18ed0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
18ee0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
18ef0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
18f00 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
18f10 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65   authorized. The
18f20 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
18f30 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
18f40 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
18f50 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
18f60 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
18f70 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
18f80 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
18f90 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
18fa0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
18fb0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  zed..**.** An au
18fc0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
18fd0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
18fe0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
18ff0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
19000 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
19010 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
19020 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
19030 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
19040 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
19050 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
19060 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
19070 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
19080 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
19090 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
190a0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
190b0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
190c0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
190d0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
190e0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
190f0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
19100 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
19110 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
19120 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
19130 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
19140 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
19150 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
19160 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
19170 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
19180 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
19190 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
191a0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
191b0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
191c0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
191d0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
191e0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
191f0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
19200 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
19210 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
19220 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
19230 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
19240 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
19250 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
19260 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
19270 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
19280 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
19290 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
192a0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
192b0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
192c0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
192d0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
192e0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
192f0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
19300 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
19310 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
19320 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
19330 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
19340 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20  zer..**.** Only 
19350 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
19360 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
19370 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
19380 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
19390 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
193a0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
193b0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
193c0 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
193d0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20   previous call. 
193e0 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74   Disable the aut
193f0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
19400 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
19410 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
19420 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
19430 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
19440 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
19450 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
19460 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
19470 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
19480 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
19490 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
194a0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
194b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
194c0 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
194d0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
194e0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
194f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
19500 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
19510 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
19520 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
19530 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
19540 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
19550 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 57 68  agraph..**.** Wh
19560 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
19570 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
19580 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
19590 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
195a0 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
195b0 20 62 65 20 72 65 70 72 65 70 61 72 65 64 20 64   be reprepared d
195c0 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  uring [sqlite3_s
195d0 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20  tep()] due to a 
195e0 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67  .** schema chang
195f0 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61  e.  Hence, the a
19600 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
19610 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  d ensure that th
19620 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74  e.** correct aut
19630 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19640 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63   remains in plac
19650 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71  e during the [sq
19660 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
19670 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
19680 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19690 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
196a0 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
196b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
196c0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
196d0 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
196e0 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
196f0 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
19700 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
19710 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
19720 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
19730 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
19740 2a 20 7b 48 31 32 35 30 31 7d 20 54 68 65 20 5b  * {H12501} The [
19750 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
19760 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69  orizer(D,...)] i
19770 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
19780 72 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  rs a.**         
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 77 69 74 68 20 64 61 74 61 62 61  back with databa
197b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
197c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 32 7d 20  .**.** {H12502} 
197d0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
197e0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
197f0 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
19800 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20  ents are.**     
19810 20 20 20 20 20 62 65 69 6e 67 20 70 61 72 73 65       being parse
19820 65 64 20 61 6e 64 20 63 6f 6d 70 69 6c 65 64 2e  ed and compiled.
19830 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 33 7d 20  .**.** {H12503} 
19840 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
19850 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
19860 6e 73 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ns any value oth
19870 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
19880 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f      [SQLITE_IGNO
19890 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
198a0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
198b0 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  Y], then.**     
198c0 20 20 20 20 20 74 68 65 20 61 70 70 6c 69 63 61       the applica
198d0 74 69 6f 6e 20 69 6e 74 65 72 66 61 63 65 20 63  tion interface c
198e0 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64 0a  all that caused.
198f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
19900 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19910 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c  ack to run shall
19920 20 66 61 69 6c 20 77 69 74 68 20 61 6e 0a 2a 2a   fail with an.**
19930 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
19940 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63  E_ERROR] error c
19950 6f 64 65 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  ode and an appro
19960 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
19970 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  sage..**.** {H12
19980 35 30 34 7d 20 57 68 65 6e 20 74 68 65 20 61 75  504} When the au
19990 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
199a0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
199b0 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70 65 72 61  E_OK], the opera
199c0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
199d0 20 64 65 73 63 72 69 62 65 64 20 69 73 20 70 72   described is pr
199e0 6f 63 65 73 73 65 64 20 6e 6f 72 6d 61 6c 6c 79  ocessed normally
199f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 35 7d  ..**.** {H12505}
19a00 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72   When the author
19a10 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
19a20 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
19a30 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20 20 20 20  NY], the.**     
19a40 20 20 20 20 20 61 70 70 6c 69 63 61 74 69 6f 6e       application
19a50 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
19a60 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 0a  that caused the.
19a70 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68  **          auth
19a80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
19a90 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69  to run shall fai
19aa0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  l.**          wi
19ab0 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 45 52  th an [SQLITE_ER
19ac0 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20  ROR] error code 
19ad0 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
19ae0 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  sage.**         
19af0 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
19b00 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
19b10 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 36  d..**.** {H12506
19b20 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  } If the authori
19b30 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e  zer code (the 2n
19b40 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
19b50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a  he authorizer.**
19b60 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
19b70 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ck) is [SQLITE_R
19b80 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61 75 74  EAD] and the aut
19b90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19ba0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
19bb0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 47 4e       [SQLITE_IGN
19bc0 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  ORE], then the p
19bd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
19be0 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
19bf0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
19c00 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20 76 61  insert a NULL va
19c10 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
19c20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
19c30 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
19c40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 65  .**          bee
19c50 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
19c60 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
19c70 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eturned..**.** {
19c80 48 31 32 35 30 37 7d 20 49 66 20 74 68 65 20 61  H12507} If the a
19c90 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28  uthorizer code (
19ca0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
19cb0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
19cc0 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zer.**          
19cd0 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 61 6e 79  callback) is any
19ce0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
19cf0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 2c 20   [SQLITE_READ], 
19d00 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
19d10 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b 53 51   a return of [SQ
19d20 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68 61 73  LITE_IGNORE] has
19d30 20 74 68 65 20 73 61 6d 65 20 65 66 66 65 63 74   the same effect
19d40 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   as [SQLITE_DENY
19d50 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 30  ]..**.** {H12510
19d60 7d 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  } The first para
19d70 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
19d80 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19d90 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
19da0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74 68            the th
19db0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
19dc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
19dd0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
19de0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
19df0 20 7b 48 31 32 35 31 31 7d 20 54 68 65 20 73 65   {H12511} The se
19e00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
19e10 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
19e20 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
19e30 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
19e40 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
19e50 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
19e60 69 65 73 20 74 68 65 20 70 61 72 74 69 63 75 6c  ies the particul
19e70 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  ar action.**    
19e80 20 20 20 20 20 20 74 6f 20 62 65 20 61 75 74 68        to be auth
19e90 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orized..**.** {H
19ea0 31 32 35 31 32 7d 20 54 68 65 20 74 68 69 72 64  12512} The third
19eb0 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
19ec0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
19ed0 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a 2a 2a   callback are.**
19ee0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
19ef0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
19f00 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 0a 2a  s that contain.*
19f10 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 69 74  *          addit
19f20 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62  ional details ab
19f30 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74  out the action t
19f40 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
19f50 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 30 7d 20  .**.** {H12520} 
19f60 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
19f70 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
19f80 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69 64 65  izer()] override
19f90 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  s.**          an
19fa0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69 6e 73  y previously ins
19fb0 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69 7a 65  talled authorize
19fc0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 31  r..**.** {H12521
19fd0 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f 72 69  } A NULL authori
19fe0 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74 20 6e  zer means that n
19ff0 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  o authorization.
1a000 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
1a010 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
1a020 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 32 7d 20  .**.** {H12522} 
1a030 54 68 65 20 64 65 66 61 75 6c 74 20 61 75 74 68  The default auth
1a040 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c 2e 0a  orizer is NULL..
1a050 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
1a060 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
1a070 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
1a080 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
1a090 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
1a0a0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1a0b0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1a0c0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
1a0d0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
1a0e0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1a0f0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
1a100 64 65 73 20 7b 48 31 32 35 39 30 7d 20 3c 48 31  des {H12590} <H1
1a110 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  2500>.**.** The 
1a120 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1a130 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1a140 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1a150 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1a160 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1a170 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1a180 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1a190 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1a1a0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1a1b0 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1a1c0 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1a1d0 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1a1e0 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1a1f0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1a200 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1a210 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1a220 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1a230 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23  nformation..*/.#
1a240 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1a250 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1a260 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1a270 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1a280 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1a290 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1a2a0 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1a2b0 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1a2c0 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1a2d0 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1a2e0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1a2f0 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48   Action Codes {H
1a300 31 32 35 35 30 7d 20 3c 48 31 32 35 30 30 3e 0a  12550} <H12500>.
1a310 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1a320 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1a330 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
1a340 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
1a350 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
1a360 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
1a370 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
1a380 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
1a390 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
1a3a0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1a3b0 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
1a3c0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1a3d0 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
1a3e0 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
1a3f0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
1a400 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
1a410 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
1a420 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
1a430 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
1a440 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1a450 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
1a460 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
1a470 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
1a480 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
1a490 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
1a4a0 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
1a4b0 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
1a4c0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
1a4d0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
1a4e0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
1a4f0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
1a500 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
1a510 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
1a520 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
1a530 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
1a540 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1a550 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
1a560 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1a570 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1a580 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1a590 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1a5a0 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1a5b0 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1a5c0 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1a5d0 20 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65    The 6th parame
1a5e0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1a5f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
1a600 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
1a610 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
1a620 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
1a630 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
1a640 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
1a650 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
1a660 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
1a670 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
1a680 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
1a690 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
1a6a0 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ode..**.** INVAR
1a6b0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1a6c0 32 35 35 31 7d 20 54 68 65 20 73 65 63 6f 6e 64  2551} The second
1a6d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 61 6e   parameter to an
1a6e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1a6f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1a700 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1a710 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c  r callback] shal
1a720 6c 20 62 65 20 61 6e 20 69 6e 74 65 67 65 72 0a  l be an integer.
1a730 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
1a740 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f  ITE_COPY | autho
1a750 72 69 7a 65 72 20 63 6f 64 65 5d 20 74 68 61 74  rizer code] that
1a760 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 20   specifies what 
1a770 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  action.**       
1a780 20 20 20 69 73 20 62 65 69 6e 67 20 61 75 74 68     is being auth
1a790 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orized..**.** {H
1a7a0 31 32 35 35 32 7d 20 54 68 65 20 33 72 64 20 61  12552} The 3rd a
1a7b0 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1a7c0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  s to the.**     
1a7d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65       [sqlite3_se
1a7e0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1a7f0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c  uthorization cal
1a800 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20 20 20 20 20  lback].**       
1a810 20 20 20 73 68 61 6c 6c 20 62 65 20 70 61 72 61     shall be para
1a820 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
1a830 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
1a840 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  h.**          [S
1a850 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75 74  QLITE_COPY | aut
1a860 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 69 73  horizer code] is
1a870 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
1a880 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ond parameter..*
1a890 2a 0a 2a 2a 20 7b 48 31 32 35 35 33 7d 20 54 68  *.** {H12553} Th
1a8a0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
1a8b0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
1a8c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
1a8d0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1a8e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1a8f0 5d 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20 6e  ] shall be the n
1a900 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
1a910 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1a920 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22  (example: "main"
1a930 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 2e 29 20  , "temp", etc.) 
1a940 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a  if applicable..*
1a950 2a 0a 2a 2a 20 7b 48 31 32 35 35 34 7d 20 54 68  *.** {H12554} Th
1a960 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
1a970 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
1a980 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f     [sqlite3_set_
1a990 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1a9a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1a9b0 5d 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20 6e  ] shall be the n
1a9c0 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
1a9d0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
1a9e0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
1a9f0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
1aa00 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20  sible for.**    
1aa10 20 20 20 20 20 20 74 68 65 20 61 63 63 65 73 73        the access
1aa20 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
1aa30 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
1aa40 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
1aa50 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  tly from.**     
1aa60 20 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53       top-level S
1aa70 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
1aa80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aa90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aaa0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
1aab0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
1aac0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
1aad0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1aae0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1aaf0 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
1ab00 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1ab10 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ab20 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ab30 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1ab40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ab50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ab60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ab70 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1ab80 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
1ab90 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1aba0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1abb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1abc0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1abd0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
1abe0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1abf0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1ac00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ac10 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1ac20 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
1ac30 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1ac40 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1ac50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ac60 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1ac70 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
1ac80 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1ac90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1aca0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1acb0 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
1acc0 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
1acd0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1ace0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1acf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ad00 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
1ad10 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
1ad20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1ad30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ad40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ad50 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
1ad60 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
1ad70 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1ad80 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ad90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ada0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
1adb0 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
1adc0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1add0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1ade0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1adf0 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
1ae00 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
1ae10 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1ae20 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1ae30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ae40 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
1ae50 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
1ae60 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1ae70 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1ae80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1ae90 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
1aea0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
1aeb0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1aec0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1aed0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1aee0 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
1aef0 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
1af00 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1af10 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1af20 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1af30 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1af40 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
1af50 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1af60 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1af70 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1af80 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
1af90 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
1afa0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1afb0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1afc0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1afd0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
1afe0 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
1aff0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1b000 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b010 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
1b020 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
1b030 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b040 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b050 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b060 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
1b070 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
1b080 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
1b090 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
1b0a0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
1b0b0 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
1b0c0 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
1b0d0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b0e0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1b0f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b100 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
1b110 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
1b120 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1b130 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b140 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b150 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
1b160 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
1b170 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1b180 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b190 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b1a0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
1b1b0 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
1b1c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b1d0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1b1e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b1f0 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
1b200 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
1b210 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
1b220 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b230 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b240 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
1b250 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
1b260 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
1b270 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b280 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b290 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
1b2a0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
1b2b0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
1b2c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1b2d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b2e0 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
1b2f0 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
1b300 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
1b310 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b320 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1b330 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
1b340 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
1b350 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1b360 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b370 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1b380 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
1b390 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
1b3a0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1b3b0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1b3c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1b3d0 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
1b3e0 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
1b3f0 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1b400 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1b410 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
1b420 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
1b430 20 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f   31   /* Functio
1b440 6e 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  n Name   NULL   
1b450 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b460 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
1b470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b480 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
1b490 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
1b4a0 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
1b4b0 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
1b4c0 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 32 32   Functions {H122
1b4d0 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 20  80} <S60400>.** 
1b4e0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
1b4f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1b500 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
1b510 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
1b520 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
1b530 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
1b540 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
1b550 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
1b560 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1b570 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
1b580 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1b590 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
1b5a0 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
1b5b0 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
1b5c0 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
1b5d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
1b5e0 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
1b5f0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1b600 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   The callback re
1b610 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65  turns a UTF-8 re
1b620 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53  ndering of the S
1b630 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1b640 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74  t.** as the stat
1b650 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
1b660 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41  ns executing.  A
1b670 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61  dditional callba
1b680 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  cks occur.** as 
1b690 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
1b6a0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
1b6b0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
1b6c0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
1b6d0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
1b6e0 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
1b6f0 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
1b700 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a   the trigger..**
1b710 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
1b720 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1b730 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1b740 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
1b750 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
1b760 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
1b770 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70 72 6f  nishes.  The pro
1b780 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
1b790 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
1b7a0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
1b7b0 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
1b7c0 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
1b7d0 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
1b7e0 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
1b7f0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
1b800 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  un..**.** INVARI
1b810 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
1b820 32 38 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63  281} The callbac
1b830 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1b840 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65  tered by [sqlite
1b850 33 5f 74 72 61 63 65 28 29 5d 20 0a 2a 2a 20 20  3_trace()] .**  
1b860 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 62 65          shall be
1b870 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20 20   invoked.**     
1b880 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 6e       whenever an
1b890 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
1b8a0 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 65  irst begins to e
1b8b0 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20  xecute and.**   
1b8c0 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20         whenever 
1b8d0 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f  a trigger subpro
1b8e0 67 72 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e  gram first begin
1b8f0 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  s to run..**.** 
1b900 7b 48 31 32 32 38 32 7d 20 45 61 63 68 20 63 61  {H12282} Each ca
1b910 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ll to [sqlite3_t
1b920 72 61 63 65 28 29 5d 20 73 68 61 6c 6c 20 6f 76  race()] shall ov
1b930 65 72 72 69 64 65 20 74 68 65 20 70 72 65 76 69  erride the previ
1b940 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ously.**        
1b950 20 20 72 65 67 69 73 74 65 72 65 64 20 74 72 61    registered tra
1b960 63 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ce callback..**.
1b970 2a 2a 20 7b 48 31 32 32 38 33 7d 20 41 20 4e 55  ** {H12283} A NU
1b980 4c 4c 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  LL trace callbac
1b990 6b 20 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20  k shall disable 
1b9a0 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  tracing..**.** {
1b9b0 48 31 32 32 38 34 7d 20 54 68 65 20 66 69 72 73  H12284} The firs
1b9c0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
1b9d0 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
1b9e0 20 73 68 61 6c 6c 20 62 65 20 61 20 63 6f 70 79   shall be a copy
1b9f0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
1ba00 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63  the pointer whic
1ba10 68 20 77 61 73 20 74 68 65 20 33 72 64 20 61 72  h was the 3rd ar
1ba20 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
1ba30 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a  e3_trace()]..**.
1ba40 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54 68 65 20  ** {H12285} The 
1ba50 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1ba60 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
1ba70 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20  lback is a.**   
1ba80 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1ba90 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1baa0 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
1bab0 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 78 74  he original text
1bac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
1bad0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1bae0 74 20 61 73 20 69 74 20 77 61 73 20 70 61 73 73  t as it was pass
1baf0 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33  ed into [sqlite3
1bb00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
1bb10 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
1bb20 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72  e equivalent, or
1bb30 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20   an SQL comment 
1bb40 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 62  indicating the b
1bb50 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20  eginning.**     
1bb60 20 20 20 20 20 6f 66 20 61 20 74 72 69 67 67 65       of a trigge
1bb70 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a  r subprogram..**
1bb80 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20 54 68 65  .** {H12287} The
1bb90 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1bba0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1bbb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
1bbc0 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a  e()] is invoked.
1bbd0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 65  **          as e
1bbe0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1bbf0 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a  t finishes..**.*
1bc00 2a 20 7b 48 31 32 32 38 38 7d 20 54 68 65 20 66  * {H12288} The f
1bc10 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1bc20 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
1bc30 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
1bc40 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
1bc50 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
1bc60 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  r to [sqlite3_pr
1bc70 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ofile()]..**.** 
1bc80 7b 48 31 32 32 38 39 7d 20 54 68 65 20 73 65 63  {H12289} The sec
1bc90 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1bca0 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   the profile cal
1bcb0 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20  lback is a.**   
1bcc0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
1bcd0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1bce0 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ing that contain
1bcf0 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74  s the complete t
1bd00 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ext of.**       
1bd10 20 20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65     the SQL state
1bd20 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70  ment as it was p
1bd30 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73 71 6c  rocessed by [sql
1bd40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1bd50 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
1bd60 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
1bd70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39 30 7d  ..**.** {H12290}
1bd80 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
1bd90 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
1bda0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ile callback is 
1bdb0 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20  an estimate.**  
1bdc0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6e          of the n
1bdd0 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63  umber of nanosec
1bde0 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  onds of wall-clo
1bdf0 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72 65 64  ck time required
1be00 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1be10 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  run the SQL stat
1be20 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 72 74  ement from start
1be30 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 53   to finish..*/.S
1be40 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
1be50 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
1be60 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
1be70 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
1be80 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1be90 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
1bea0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
1beb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
1bec0 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
1bed0 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
1bee0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
1bef0 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
1bf00 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
1bf10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
1bf20 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
1bf30 6c 62 61 63 6b 73 20 7b 48 31 32 39 31 30 7d 20  lbacks {H12910} 
1bf40 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60400>.**.** T
1bf50 68 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66  his routine conf
1bf60 69 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63  igures a callbac
1bf70 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65  k function - the
1bf80 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c  .** progress cal
1bf90 6c 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20  lback - that is 
1bfa0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
1bfb0 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
1bfc0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  .** running call
1bfd0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  s to [sqlite3_ex
1bfe0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
1bff0 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  step()] and.** [
1c000 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1c010 65 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c  e()].  An exampl
1c020 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
1c030 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
1c040 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
1c050 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
1c060 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
1c070 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73   If the progress
1c080 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1c090 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
1c0a0 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
1c0b0 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
1c0c0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
1c0d0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
1c0e0 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
1c0f0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
1c100 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
1c110 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1c120 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1c130 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  r must not do an
1c140 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1c150 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1c160 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c170 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1c180 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1c190 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
1c1a0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1c1b0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1c1c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1c1d0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1c1e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1c1f0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1c200 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1c210 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1c220 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 4e  agraph..**.** IN
1c230 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1c240 7b 48 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c  {H12911} The cal
1c250 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1c260 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1c270 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1c280 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20  ndler().**      
1c290 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70      is invoked p
1c2a0 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
1c2b0 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
1c2c0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20  calls to.**     
1c2d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74       [sqlite3_st
1c2e0 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ep()]..**.** {H1
1c2f0 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65  2912} The progre
1c300 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ss callback is i
1c310 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
1c320 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a  every N virtual.
1c330 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63 68  **          mach
1c340 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65  ine opcodes, whe
1c350 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
1c360 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
1c370 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
1c380 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1c390 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c  _handler()] call
1c3a0 20 74 68 61 74 20 72 65 67 69 73 74 65 72 65 64   that registered
1c3b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1c3c0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 4e   callback.  If N
1c3d0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 2c   is less than 1,
1c3e0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1c3f0 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20  s_handler().**  
1c400 20 20 20 20 20 20 20 20 61 63 74 73 20 61 73 20          acts as 
1c410 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67 72 65  if a NULL progre
1c420 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64 20 62  ss handler had b
1c430 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e 0a 2a  een specified..*
1c440 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20 54 68  *.** {H12913} Th
1c450 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
1c460 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64  ack itself is id
1c470 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
1c480 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20  third.**        
1c490 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71    argument to sq
1c4a0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1c4b0 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20  andler()..**.** 
1c4c0 7b 48 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75  {H12914} The fou
1c4d0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
1c4e0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1c4f0 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20 61 0a  _handler() is a.
1c500 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f 69 64  **          void
1c510 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
1c520 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  to the progress 
1c530 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
1c540 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 61       function ea
1c550 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e  ch time it is in
1c560 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  voked..**.** {H1
1c570 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20  2915} If a call 
1c580 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
1c590 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66  ()] results in f
1c5a0 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f  ewer than N opco
1c5b0 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  des.**          
1c5c0 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c 20  being executed, 
1c5d0 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73  then the progres
1c5e0 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65  s callback is ne
1c5f0 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a  ver invoked..**.
1c600 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45 76 65 72  ** {H12916} Ever
1c610 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  y call to [sqlit
1c620 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1c630 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ler()].**       
1c640 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e     overwrites an
1c650 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  y previously reg
1c660 69 73 74 65 72 65 64 20 70 72 6f 67 72 65 73 73  istered progress
1c670 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1c680 7b 48 31 32 39 31 37 7d 20 49 66 20 74 68 65 20  {H12917} If the 
1c690 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1c6a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1c6b0 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65  L then no progre
1c6c0 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  ss.**          h
1c6d0 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65  andler is invoke
1c6e0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 38  d..**.** {H12918
1c6f0 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  } If the progres
1c700 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
1c710 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65  ns a result othe
1c720 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a  r than 0, then.*
1c730 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
1c740 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 20  ehavior is a if 
1c750 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
1c760 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63  pt()] had been c
1c770 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20  alled..**       
1c780 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f 0a 76     <S30500>.*/.v
1c790 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
1c7a0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
1c7b0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
1c7c0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
1c7d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c7e0 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
1c7f0 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
1c800 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c  ction {H12700} <
1c810 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40200>.**.** Th
1c820 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
1c830 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
1c840 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20  base file whose 
1c850 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79  name is given by
1c860 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
1c870 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 66   argument. The f
1c880 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1c890 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1c8a0 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
1c8b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1c8c0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1c8d0 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
1c8e0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1c8f0 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
1c900 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
1c910 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61 73 65  6(). A [database
1c920 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1c930 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1c940 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1c950 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1c960 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1c970 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1c980 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1c990 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1c9a0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1c9b0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1c9c0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1c9d0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1c9e0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1c9f0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1ca00 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1ca10 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1ca20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65 20 64  object. If the d
1ca30 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1ca40 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
1ca50 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
1ca60 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
1ca70 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
1ca80 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
1ca90 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1caa0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a  returned.  The.*
1cab0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1cac0 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
1cad0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
1cae0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
1caf0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
1cb00 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
1cb10 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
1cb20 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a  f the error..**.
1cb30 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 65  ** The default e
1cb40 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
1cb50 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1cb60 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
1cb70 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1cb80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1cb90 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
1cba0 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
1cbb0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1cbc0 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
1cbd0 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
1cbe0 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
1cbf0 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
1cc00 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
1cc10 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
1cc20 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1cc30 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
1cc40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1cc50 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
1cc60 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
1cc70 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
1cc80 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
1cc90 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
1cca0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
1ccb0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
1ccc0 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
1ccd0 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
1cce0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
1ccf0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1cd00 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
1cd10 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
1cd20 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
1cd30 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
1cd40 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1cd50 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
1cd60 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
1cd70 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  r can take one o
1cd80 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
1cd90 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
1cda0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1cdb0 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
1cdc0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
1cdd0 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c 49  OMUTEX] or [SQLI
1cde0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1cdf0 58 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20  X] flags:.**.** 
1ce00 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  <dl>.** <dt>[SQL
1ce10 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1ce20 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
1ce30 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1ce40 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
1ce50 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
1ce60 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1ce70 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
1ce80 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1ce90 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a   returned.</dd>.
1cea0 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54  **.** <dt>[SQLIT
1ceb0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1cec0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1ced0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1cee0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1cef0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
1cf00 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
1cf10 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
1cf20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
1cf30 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
1cf40 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1cf50 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
1cf60 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
1cf70 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
1cf80 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
1cf90 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
1cfa0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  eturned.</dd>.**
1cfb0 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  .** <dt>[SQLITE_
1cfc0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
1cfd0 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
1cfe0 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
1cff0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1d000 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1d010 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1d020 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
1d030 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f  s it if.** it do
1d040 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
1d050 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
1d060 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
1d070 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
1d080 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
1d090 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1d0a0 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a  _open16().</dd>.
1d0b0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
1d0c0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
1d0d0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1d0e0 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
1d0f0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
1d100 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
1d110 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66   above or one of
1d120 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e   the combination
1d130 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f  s shown above co
1d140 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74  mbined.** with t
1d150 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1d160 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b 53 51 4c  NOMUTEX] or [SQL
1d170 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
1d180 45 58 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68  EX] flags,.** th
1d190 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1d1a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
1d1b0 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c 49  .** If the [SQLI
1d1c0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1d1d0 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
1d1e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1d1f0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
1d200 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
1d210 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
1d220 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
1d230 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
1d240 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
1d250 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
1d260 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
1d270 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 49  r start-time.  I
1d280 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
1d290 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
1d2a0 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
1d2b0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
1d2c0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
1d2d0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
1d2e0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
1d2f0 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
1d300 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
1d310 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
1d320 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
1d330 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
1d340 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ime..**.** If th
1d350 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
1d360 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
1d370 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1d380 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
1d390 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
1d3a0 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
1d3b0 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69  nection.  This i
1d3c0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1d3d0 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
1d3e0 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
1d3f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1d400 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
1d410 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1d420 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
1d430 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
1d440 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
1d450 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
1d460 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
1d470 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
1d480 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1d490 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
1d4a0 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
1d4b0 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
1d4c0 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
1d4d0 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
1d4e0 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
1d4f0 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
1d500 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
1d510 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
1d520 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
1d530 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
1d540 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
1d550 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76  ing, then a priv
1d560 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a  ate, temporary.*
1d570 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  * on-disk databa
1d580 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
1d590 65 64 2e 20 20 54 68 69 73 20 70 72 69 76 61 74  ed.  This privat
1d5a0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1d5b0 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
1d5c0 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
1d5d0 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
1d5e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1d5f0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
1d600 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
1d610 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1d620 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
1d630 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
1d640 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1d650 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
1d660 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
1d670 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
1d680 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
1d690 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d6a0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
1d6b0 20 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20    If the fourth 
1d6c0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1d6d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1d6e0 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
1d6f0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1d700 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
1d710 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
1d720 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
1d730 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
1d740 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
1d750 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
1d760 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
1d770 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1d780 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
1d790 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
1d7a0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
1d7b0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
1d7c0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
1d7d0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
1d7e0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
1d7f0 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
1d800 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
1d810 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
1d820 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
1d830 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1d840 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
1d850 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e  n_v2()..**.** IN
1d860 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1d870 7b 48 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71  {H12701} The [sq
1d880 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1d890 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1d8a0 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ], and.**       
1d8b0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
1d8c0 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
1d8d0 73 20 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a  s create a new.*
1d8e0 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
1d8f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d900 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1d910 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1d920 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 67   database file g
1d930 69 76 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69  iven in their fi
1d940 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  rst parameter..*
1d950 2a 0a 2a 2a 20 7b 48 31 32 37 30 32 7d 20 54 68  *.** {H12702} Th
1d960 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1d970 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
1d980 65 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20  ed as UTF-8.**  
1d990 20 20 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c          for [sql
1d9a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  ite3_open()] and
1d9b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1d9c0 32 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d  2()] and as UTF-
1d9d0 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  16.**          i
1d9e0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1d9f0 65 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c  e order for [sql
1da00 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
1da10 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 33 7d 20 41  **.** {H12703} A
1da20 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
1da30 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1da40 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1da50 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a  ite3_open16()],.
1da60 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
1da70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1da80 29 5d 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e  )] writes a poin
1da90 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20  ter to a new.** 
1daa0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1dab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
1dac0 6e 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a  nto *ppDb..**.**
1dad0 20 7b 48 31 32 37 30 34 7d 20 54 68 65 20 5b 73   {H12704} The [s
1dae0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
1daf0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
1db00 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  )], and.**      
1db10 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1db20 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
1db30 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1db40 45 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65  E_OK] upon succe
1db50 73 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss,.**          
1db60 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
1db70 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
1db80 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  n failure..**.**
1db90 20 7b 48 31 32 37 30 36 7d 20 54 68 65 20 64 65   {H12706} The de
1dba0 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64  fault text encod
1dbb0 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61  ing for a new da
1dbc0 74 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75  tabase created u
1dbd0 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
1dbe0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1dbf0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
1dc00 65 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65  en_v2()] will be
1dc10 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
1dc20 31 32 37 30 37 7d 20 54 68 65 20 64 65 66 61 75  12707} The defau
1dc30 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  lt text encoding
1dc40 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62   for a new datab
1dc50 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  ase created usin
1dc60 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
1dc70 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1dc80 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e   will be UTF-16.
1dc90 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 39 7d 20  .**.** {H12709} 
1dca0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
1dcb0 6e 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  n(F,D)] interfac
1dcc0 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  e is equivalent 
1dcd0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
1dce0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1dcf0 46 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20  F,D,G,0)] where 
1dd00 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
1dd10 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  is.**          [
1dd20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1dd30 57 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f  WRITE]|[SQLITE_O
1dd40 50 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a  PEN_CREATE]..**.
1dd50 2a 2a 20 7b 48 31 32 37 31 31 7d 20 49 66 20 74  ** {H12711} If t
1dd60 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
1dd70 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
1dd80 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e  v2(F,D,G,V)] con
1dd90 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  tains the.**    
1dda0 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
1ddb0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1ddc0 44 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20  DONLY] then the 
1ddd0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1dde0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ed.**          f
1ddf0 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e  or reading only.
1de00 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 32 7d 20  .**.** {H12712} 
1de10 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74  If the G paramet
1de20 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  er to [sqlite3_o
1de30 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d  pen_v2(F,D,G,V)]
1de40 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a   contains the.**
1de50 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61            bit va
1de60 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  lue [SQLITE_OPEN
1de70 5f 52 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e  _READWRITE] then
1de80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1de90 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20   opened.**      
1dea0 20 20 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20      reading and 
1deb0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
1dec0 62 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64  ble, or for read
1ded0 69 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a  ing only if the.
1dee0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
1def0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
1df00 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
1df10 74 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a  ting system..**.
1df20 2a 2a 20 7b 48 31 32 37 31 33 7d 20 49 66 20 74  ** {H12713} If t
1df30 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
1df40 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
1df50 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69  v2(F,D,G,V)] omi
1df60 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
1df70 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
1df80 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1df90 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  ] and the databa
1dfa0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  se does not.**  
1dfb0 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73          previous
1dfc0 6c 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  ly exist, an err
1dfd0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  or is returned..
1dfe0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 34 7d 20 49  **.** {H12714} I
1dff0 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
1e000 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
1e010 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
1e020 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
1e030 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
1e040 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
1e050 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20  CREATE] and the 
1e060 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1e070 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  t.**          pr
1e080 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20  eviously exist, 
1e090 74 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20  then an attempt 
1e0a0 69 73 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74  is made to creat
1e0b0 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  e and.**        
1e0c0 20 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65    initialize the
1e0d0 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a   database..**.**
1e0e0 20 7b 48 31 32 37 31 37 7d 20 49 66 20 74 68 65   {H12717} If the
1e0f0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1e100 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
1e110 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1e120 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20  _open16()],.**  
1e130 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
1e140 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
1e150 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
1e160 65 6e 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a  en an private,.*
1e170 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d  *          ephem
1e180 65 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20  eral, in-memory 
1e190 64 61 74 61 62 61 73 65 20 69 73 20 63 72 65 61  database is crea
1e1a0 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
1e1b0 65 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20  ection..**      
1e1c0 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c      <todo>Is SQL
1e1d0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c  ITE_OPEN_CREATE|
1e1e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1e1f0 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a  WRITE required.*
1e200 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71  *          in sq
1e210 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f  lite3_open_v2()?
1e220 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48  </todo>.**.** {H
1e230 31 32 37 31 39 7d 20 49 66 20 74 68 65 20 66 69  12719} If the fi
1e240 6c 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f  lename is NULL o
1e250 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
1e260 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1e270 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  e,.**          e
1e280 70 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b  phemeral on-disk
1e290 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1e2a0 65 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20  e created..**   
1e2b0 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20         <todo>Is 
1e2c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1e2d0 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  TE|SQLITE_OPEN_R
1e2e0 45 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65  EADWRITE require
1e2f0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  d.**          in
1e300 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1e310 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  ()?</todo>.**.**
1e320 20 7b 48 31 32 37 32 31 7d 20 54 68 65 20 5b 64   {H12721} The [d
1e330 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e340 6f 6e 5d 20 63 72 65 61 74 65 64 20 62 79 20 5b  on] created by [
1e350 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1e360 46 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20 20 20  F,D,G,V)].**    
1e370 20 20 20 20 20 20 77 69 6c 6c 20 75 73 65 20 74        will use t
1e380 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1e390 20 6f 62 6a 65 63 74 20 69 64 65 6e 74 69 66 69   object identifi
1e3a0 65 64 20 62 79 20 74 68 65 20 56 20 70 61 72 61  ed by the V para
1e3b0 6d 65 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20  meter,.**       
1e3c0 20 20 20 6f 72 20 74 68 65 20 64 65 66 61 75 6c     or the defaul
1e3d0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1e3e0 6f 62 6a 65 63 74 20 69 66 20 56 20 69 73 20 61  object if V is a
1e3f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1e400 2a 0a 2a 2a 20 7b 48 31 32 37 32 33 7d 20 54 77  *.** {H12723} Tw
1e410 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
1e420 65 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20 73 68  ections] will sh
1e430 61 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63  are a common cac
1e440 68 65 20 69 66 20 62 6f 74 68 20 77 65 72 65 0a  he if both were.
1e450 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65 6e  **          open
1e460 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
1e470 20 56 46 53 20 77 68 69 6c 65 20 5b 73 68 61 72   VFS while [shar
1e480 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 77  ed cache mode] w
1e490 61 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 0a 2a  as enabled and.*
1e4a0 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 62 6f  *          if bo
1e4b0 74 68 20 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d  th filenames com
1e4c0 70 61 72 65 20 65 71 75 61 6c 20 75 73 69 6e 67  pare equal using
1e4d0 20 6d 65 6d 63 6d 70 28 29 20 61 66 74 65 72 20   memcmp() after 
1e4e0 68 61 76 69 6e 67 20 62 65 65 6e 0a 2a 2a 20 20  having been.**  
1e4f0 20 20 20 20 20 20 20 20 70 72 6f 63 65 73 73 65          processe
1e500 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
1e510 33 5f 76 66 73 20 7c 20 78 46 75 6c 6c 50 61 74  3_vfs | xFullPat
1e520 68 6e 61 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66  hname] method of
1e530 20 74 68 65 20 56 46 53 2e 0a 2a 2f 0a 69 6e 74   the VFS..*/.int
1e540 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
1e550 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
1e560 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1e570 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1e580 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
1e590 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
1e5a0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1e5b0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
1e5c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
1e5d0 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
1e5e0 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
1e5f0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1e600 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
1e610 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1e620 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
1e630 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1e640 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
1e650 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
1e660 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
1e670 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1e680 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1e690 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
1e6a0 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
1e6b0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1e6c0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
1e6d0 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
1e6e0 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
1e6f0 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
1e700 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
1e710 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
1e720 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
1e730 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e740 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
1e750 6e 64 20 4d 65 73 73 61 67 65 73 20 7b 48 31 32  nd Messages {H12
1e760 38 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a  800} <S60200>.**
1e770 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1e780 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
1e790 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1e7a0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
1e7b0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
1e7c0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1e7d0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
1e7e0 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
1e7f0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
1e800 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1e810 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1e820 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
1e830 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
1e840 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
1e850 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
1e860 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
1e870 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
1e880 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
1e890 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
1e8a0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 54 68 65   undefined.  The
1e8b0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1e8c0 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
1e8d0 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
1e8e0 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
1e8f0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
1e900 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
1e910 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1e920 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
1e930 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1e940 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
1e950 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1e960 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
1e970 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
1e980 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
1e990 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
1e9a0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
1e9b0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
1e9c0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
1e9d0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
1e9e0 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  ively..** Memory
1e9f0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
1ea00 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
1ea10 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
1ea20 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
1ea30 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1ea40 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
1ea50 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
1ea60 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
1ea70 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
1ea80 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
1ea90 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
1eaa0 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
1eab0 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
1eac0 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
1ead0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
1eae0 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
1eaf0 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
1eb00 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
1eb10 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
1eb20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
1eb30 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
1eb40 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
1eb50 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
1eb60 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
1eb70 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
1eb80 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
1eb90 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
1eba0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
1ebb0 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
1ebc0 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
1ebd0 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
1ebe0 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
1ebf0 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
1ec00 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
1ec10 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
1ec20 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
1ec30 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
1ec40 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
1ec50 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
1ec60 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
1ec70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1ec80 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
1ec90 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
1eca0 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
1ecb0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
1ecc0 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
1ecd0 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
1ece0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
1ecf0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
1ed00 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
1ed10 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
1ed20 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
1ed30 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
1ed40 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
1ed50 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
1ed60 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
1ed70 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
1ed80 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
1ed90 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
1eda0 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
1edb0 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
1edc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
1edd0 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
1ede0 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
1edf0 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
1ee00 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
1ee10 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1ee20 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30  TS:.**.** {H1280
1ee30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1ee40 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e 74 65  errcode(D)] inte
1ee50 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1ee60 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20  e numeric.**    
1ee70 20 20 20 20 20 20 5b 72 65 73 75 6c 74 20 63 6f        [result co
1ee80 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
1ee90 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
1eea0 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
1eeb0 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tly.**          
1eec0 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65  failed interface
1eed0 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
1eee0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
1eef0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1ef00 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 32  D..**.** {H12802
1ef10 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
1ef20 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
1ef30 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  D)] interface re
1ef40 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1ef50 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65  c.**          [e
1ef60 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1ef70 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1ef80 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20  t recently.**   
1ef90 20 20 20 20 20 20 20 66 61 69 6c 65 64 20 69 6e         failed in
1efa0 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73  terface call ass
1efb0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1efc0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1efd0 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
1efe0 7b 48 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71  {H12803} The [sq
1eff0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d  lite3_errmsg(D)]
1f000 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72   and [sqlite3_er
1f010 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20  rmsg16(D)].**   
1f020 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
1f030 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  s return English
1f040 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74  -language text t
1f050 68 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a  hat describes.**
1f060 20 20 20 20 20 20 20 20 20 20 74 68 65 20 65 72            the er
1f070 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c  ror in the mostl
1f080 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65  y recently faile
1f090 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  d interface call
1f0a0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e  ,.**          en
1f0b0 63 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 20  coded as either 
1f0c0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
1f0d0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
1f0e0 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54 68 65  .** {H12807} The
1f0f0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1f100 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72  d by [sqlite3_er
1f110 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c  rmsg()] and [sql
1f120 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1f130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
1f140 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
1f150 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74   next SQLite int
1f160 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a  erface call..**.
1f170 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43 61 6c 6c  ** {H12808} Call
1f180 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65  s to API routine
1f190 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65  s that do not re
1f1a0 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f  turn an error co
1f1b0 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28  de.**          (
1f1c0 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65  example: [sqlite
1f1d0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29  3_data_count()])
1f1e0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20   do not.**      
1f1f0 20 20 20 20 63 68 61 6e 67 65 20 74 68 65 20 65      change the e
1f200 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65 73  rror code or mes
1f210 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 62 79  sage returned by
1f220 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1f230 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1f240 2c 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  , [sqlite3_exten
1f250 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a  ded_errcode()],.
1f260 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1f270 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
1f280 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
1f290 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  sg16()]..**.** {
1f2a0 48 31 32 38 30 39 7d 20 49 6e 74 65 72 66 61 63  H12809} Interfac
1f2b0 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f 74 20  es that are not 
1f2c0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1f2d0 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 20 20  a specific.**   
1f2e0 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
1f2f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 65 78   connection] (ex
1f300 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20 20 20  amples:.**      
1f310 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72      [sqlite3_mpr
1f320 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71 6c 69  intf()] or [sqli
1f330 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
1f340 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20 20 20  d_cache()].**   
1f350 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20 63 68         do not ch
1f360 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 20  ange the values 
1f370 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20  returned by.**  
1f380 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1f390 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71  _errcode()], [sq
1f3a0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
1f3b0 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20  rrcode()],.**   
1f3c0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1f3d0 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73  errmsg()], or [s
1f3e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1f3f0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1f400 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  e3_errcode(sqlit
1f410 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c  e3 *db);.int sql
1f420 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
1f430 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1f440 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
1f450 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
1f460 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
1f470 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
1f480 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
1f490 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f4a0 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
1f4b0 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30 30 7d   Object {H13000}
1f4c0 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59   <H13010>.** KEY
1f4d0 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
1f4e0 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
1f4f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1f500 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
1f510 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
1f520 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
1f530 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
1f540 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
1f550 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
1f560 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
1f570 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f580 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
1f590 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
1f5a0 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
1f5b0 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
1f5c0 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
1f5d0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
1f5e0 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
1f5f0 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
1f600 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1f610 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
1f620 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1f630 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f640 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
1f650 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
1f660 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
1f670 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
1f680 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
1f690 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1f6a0 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
1f6b0 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
1f6c0 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
1f6d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
1f6e0 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
1f6f0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1f700 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
1f710 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1f720 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
1f730 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
1f740 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
1f750 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
1f760 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
1f770 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
1f780 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
1f790 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1f7a0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
1f7b0 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
1f7c0 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
1f7d0 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
1f7e0 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
1f7f0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1f800 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
1f810 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
1f820 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
1f830 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f840 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
1f850 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30 36 30   {H12760} <S2060
1f860 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
1f870 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
1f880 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
1f890 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
1f8a0 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
1f8b0 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
1f8c0 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
1f8d0 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
1f8e0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1f8f0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1f900 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
1f910 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
1f920 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
1f930 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1f940 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
1f950 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
1f960 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
1f970 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
1f980 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
1f990 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
1f9a0 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
1f9b0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1f9c0 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
1f9d0 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54  at construct.  T
1f9e0 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
1f9f0 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69  rns the old limi
1fa00 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
1fa10 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
1fa20 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
1fa30 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
1fa40 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74  hanged..** For t
1fa50 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  he limit categor
1fa60 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49  y of SQLITE_LIMI
1fa70 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61  T_XYZ there is a
1fa80 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 62   hard upper.** b
1fa90 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20 63 6f  ound set by a co
1faa0 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65  mpile-time C pre
1fab0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
1fac0 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d 41 58  named SQLITE_MAX
1fad0 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  _XYZ..** (The "_
1fae0 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
1faf0 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
1fb00 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41  o "_MAX_".).** A
1fb10 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1fb20 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1fb30 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1fb40 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1fb50 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1fb60 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1fb70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20  er limit..**.** 
1fb80 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run time limits 
1fb90 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
1fba0 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
1fbb0 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
1fbc0 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
1fbd0 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
1fbe0 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
1fbf0 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
1fc00 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
1fc10 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
1fc20 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
1fc30 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
1fc40 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
1fc50 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72 20 74  .** webbrowser t
1fc60 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
1fc70 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
1fc80 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
1fc90 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
1fca0 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
1fcb0 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
1fcc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
1fcd0 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
1fce0 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
1fcf0 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
1fd00 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
1fd10 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
1fd20 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
1fd30 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
1fd40 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
1fd50 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
1fd60 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
1fd70 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
1fd80 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
1fd90 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
1fda0 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
1fdb0 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
1fdc0 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
1fdd0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
1fde0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1fdf0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
1fe00 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
1fe10 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
1fe20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
1fe30 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
1fe40 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
1fe50 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
1fe60 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
1fe70 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
1fe80 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1fe90 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
1fea0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
1feb0 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
1fec0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
1fed0 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
1fee0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1fef0 2a 20 7b 48 31 32 37 36 32 7d 20 41 20 73 75 63  * {H12762} A suc
1ff00 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
1ff10 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
1ff20 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69  ,C,V)] where V i
1ff30 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  s.**          po
1ff40 73 69 74 69 76 65 20 63 68 61 6e 67 65 73 20 74  sitive changes t
1ff50 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  he limit on the 
1ff60 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63  size of construc
1ff70 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  t C in the.**   
1ff80 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
1ff90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74   connection] D t
1ffa0 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20  o the lesser of 
1ffb0 56 20 61 6e 64 20 74 68 65 20 68 61 72 64 20 75  V and the hard u
1ffc0 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  pper.**         
1ffd0 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69   bound on the si
1ffe0 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69 73 20  ze of C that is 
1fff0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
20000 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ime..**.** {H127
20010 36 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  66} A successful
20020 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
20030 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20  3_limit(D,C,V)] 
20040 77 68 65 72 65 20 56 20 69 73 20 6e 65 67 61 74  where V is negat
20050 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
20060 6c 65 61 76 65 73 20 74 68 65 20 73 74 61 74 65  leaves the state
20070 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
20080 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
20090 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  unchanged..**.**
200a0 20 7b 48 31 32 37 36 39 7d 20 41 20 73 75 63 63   {H12769} A succ
200b0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
200c0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c  sqlite3_limit(D,
200d0 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68  C,V)] returns th
200e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  e.**          va
200f0 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
20100 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20   on the size of 
20110 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 74  construct C in t
20120 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
20130 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20140 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73  ion] D as it was
20150 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61   prior to the ca
20160 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ll..*/.int sqlit
20170 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
20180 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
20190 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
201a0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
201b0 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
201c0 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32  es {H12790} <H12
201d0 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  760>.** KEYWORDS
201e0 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
201f0 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  y} {limit catego
20200 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
20210 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
20220 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70 65 63  ne various aspec
20230 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62 61 73  ts of a [databas
20240 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
20250 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 69 6d   that can be lim
20260 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62 79 20  ited in size by 
20270 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
20280 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
20290 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
202a0 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
202b0 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73  s are as follows
202c0 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  :.**.** <dl>.** 
202d0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
202e0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
202f0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20300 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
20310 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
20320 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a  ble row.<dd>.**.
20330 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
20340 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
20350 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
20360 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
20370 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
20380 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
20390 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
203a0 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
203b0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
203c0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
203d0 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
203e0 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
203f0 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
20400 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74 68 65   a SELECT or the
20410 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
20420 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
20430 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
20440 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
20450 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
20460 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
20470 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
20480 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
20490 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
204a0 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
204b0 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
204c0 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  pression.</dd>.*
204d0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
204e0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
204f0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
20500 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
20510 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
20520 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
20530 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
20540 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
20550 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
20560 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
20570 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
20580 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
20590 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
205a0 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
205b0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
205c0 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
205d0 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
205e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
205f0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
20600 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20610 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
20620 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
20630 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  unction.</dd>.**
20640 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
20650 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
20660 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20670 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
20680 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
20690 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  es.</dd>.**.** <
206a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
206b0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
206c0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
206d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
206e0 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
206f0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
20700 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f  e LIKE or.** GLO
20710 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  B operators.</dd
20720 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
20730 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
20740 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
20750 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20760 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61   number of varia
20770 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73  bles in an SQL s
20780 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61  tatement that ca
20790 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f  n.** be bound.</
207a0 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  dd>.** </dl>.*/.
207b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
207c0 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
207d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
207e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
207f0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
20800 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20810 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
20820 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
20830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20840 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
20850 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
20860 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
20870 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
20880 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
20890 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
208a0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
208b0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
208c0 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
208d0 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
208e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
208f0 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
20900 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
20910 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
20920 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
20930 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
20940 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
20950 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
20960 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
20970 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
20980 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
20990 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a          9../*.**
209a0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
209b0 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
209c0 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c  ement {H13010} <
209d0 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10000>.** KEYWO
209e0 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
209f0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
20a00 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
20a10 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
20a20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
20a30 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
20a40 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
20a50 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
20a60 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
20a70 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
20a80 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
20a90 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
20aa0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
20ab0 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
20ac0 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ior call to [sql
20ad0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
20ae0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20af0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
20b00 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  en16()]..**.** T
20b10 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
20b20 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
20b30 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
20b40 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
20b50 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
20b60 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
20b70 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
20b80 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
20b90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20ba0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
20bb0 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
20bc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20bd0 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
20be0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
20bf0 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
20c00 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65  .** If the nByte
20c10 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
20c20 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
20c30 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
20c40 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
20c50 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
20c60 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e  r. If nByte is n
20c70 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
20c80 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
20c90 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
20ca0 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
20cb0 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42  m zSql.  When nB
20cc0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
20cd0 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
20ce0 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
20cf0 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
20d00 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
20d10 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
20d20 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
20d30 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
20d40 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
20d50 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
20d60 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
20d70 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
20d80 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
20d90 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
20da0 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
20db0 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
20dc0 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
20dd0 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
20de0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
20df0 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
20e00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
20e10 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
20e20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
20e30 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
20e40 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
20e50 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61  tes..**.** *pzTa
20e60 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
20e70 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
20e80 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65   byte past the e
20e90 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  nd of the.** fir
20ea0 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
20eb0 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
20ec0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63   routines only c
20ed0 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
20ee0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
20ef0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
20f00 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
20f10 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69  ng to what remai
20f20 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64  ns.** uncompiled
20f30 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20  ..**.** *ppStmt 
20f40 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
20f50 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
20f60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20f70 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
20f80 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
20f90 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
20fa0 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  )].  If there is
20fb0 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
20fc0 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
20fd0 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e  NULL.  If the in
20fe0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
20ff0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
21000 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
21010 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
21020 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
21030 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
21040 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30  o NULL..** {A130
21050 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  18} The calling 
21060 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
21070 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
21080 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
21090 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
210a0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
210b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
210c0 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
210d0 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
210e0 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
210f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
21100 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69  eturned, otherwi
21110 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
21120 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
21130 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
21140 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
21150 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
21160 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
21170 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
21180 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
21190 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
211a0 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
211b0 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
211c0 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
211d0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
211e0 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
211f0 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
21200 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22  ..** In the "v2"
21210 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
21220 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
21230 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
21240 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
21250 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
21260 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
21270 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
21280 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
21290 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
212a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
212b0 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
212c0 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65  * behave a diffe
212d0 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61  rently in two wa
212e0 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
212f0 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65  * <li>.** If the
21300 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
21310 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
21320 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
21330 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
21340 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
21350 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
21360 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
21370 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
21380 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
21390 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
213a0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
213b0 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73  again.  If the s
213c0 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65  chema has change
213d0 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68  d in.** a way th
213e0 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61  at makes the sta
213f0 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72  tement no longer
21400 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33   valid, [sqlite3
21410 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74  _step()] will st
21420 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
21430 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20  QLITE_SCHEMA].  
21440 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c  But unlike the l
21450 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20  egacy behavior, 
21460 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
21470 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61  is.** now a fata
21480 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e  l error.  Callin
21490 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
214a0 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77  re_v2()] again w
214b0 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65  ill not make the
214c0 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61  .** error go awa
214d0 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73  y.  Note: use [s
214e0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
214f0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78   to find the tex
21500 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73  t.** of the pars
21510 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72  ing error that r
21520 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51  esults in an [SQ
21530 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74  LITE_SCHEMA] ret
21540 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  urn..** </li>.**
21550 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e  .** <li>.** When
21560 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
21570 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
21580 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
21590 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
215a0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
215b0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
215c0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
215d0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
215e0 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
215f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21600 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
21610 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
21620 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
21630 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79  lt code.** and y
21640 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  ou would have to
21650 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
21660 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
21670 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65  reset()] in orde
21680 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  r.** to find the
21690 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
216a0 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
216b0 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
216c0 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
216d0 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
216e0 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
216f0 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
21700 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
21710 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ly..** </li>.** 
21720 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  </ol>.**.** INVA
21730 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
21740 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69  13011} The [sqli
21750 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a  te3_prepare(db,z
21760 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a  Sql,...)] and.**
21770 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
21780 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
21790 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ,zSql,...)] inte
217a0 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74  rfaces interpret
217b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
217c0 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a   text in their z
217d0 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73  Sql parameter as
217e0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
217f0 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  13012} The [sqli
21800 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 64 62  te3_prepare16(db
21810 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a  ,zSql,...)] and.
21820 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
21830 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
21840 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20  2(db,zSql,...)] 
21850 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72  interfaces inter
21860 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  pret the.**     
21870 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65       text in the
21880 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65  ir zSql paramete
21890 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  r as UTF-16 in t
218a0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
218b0 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  rder..**.** {H13
218c0 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74  013} If the nByt
218d0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  e argument to [s
218e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
218f0 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  2(db,zSql,nByte,
21900 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
21910 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e    and its varian
21920 74 73 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  ts is less than 
21930 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c 20 74 65  zero, the SQL te
21940 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  xt is.**        
21950 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c    read from zSql
21960 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
21970 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
21980 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
21990 7b 48 31 33 30 31 34 7d 20 49 66 20 74 68 65 20  {H13014} If the 
219a0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74  nByte argument t
219b0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
219c0 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42  re_v2(db,zSql,nB
219d0 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  yte,...)].**    
219e0 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61        and its va
219f0 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65  riants is non-ne
21a00 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20  gative, then at 
21a10 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65  most nBytes byte
21a20 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
21a30 20 53 51 4c 20 74 65 78 74 20 69 73 20 72 65 61   SQL text is rea
21a40 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a  d from zSql..**.
21a50 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49 6e 20 5b  ** {H13015} In [
21a60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21a70 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70  v2(db,zSql,N,P,p
21a80 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 73 20  zTail)] and its 
21a90 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20  variants.**     
21aa0 20 20 20 20 20 69 66 20 74 68 65 20 7a 53 71 6c       if the zSql
21ab0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
21ac0 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  ains more than o
21ad0 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ne SQL statement
21ae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
21af0 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
21b00 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69  ULL, then *pzTai
21b10 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
21b20 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  nt to the.**    
21b30 20 20 20 20 20 20 66 69 72 73 74 20 62 79 74 65        first byte
21b40 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
21b50 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
21b60 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
21b70 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74  ..**          <t
21b80 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a 70  odo>What does *p
21b90 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69  zTail point to i
21ba0 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 20 73  f there is one s
21bb0 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e  tatement?</todo>
21bc0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 36 7d 20  .**.** {H13016} 
21bd0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
21be0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  l to [sqlite3_pr
21bf0 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
21c00 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a  ,N,ppStmt,...)].
21c10 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 6f  **          or o
21c20 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
21c30 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f 20 2a  ts writes into *
21c40 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 65 72  ppStmt a pointer
21c50 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20   to a new.**    
21c60 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
21c70 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20  statement] or a 
21c80 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20  pointer to NULL 
21c90 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73  if zSql contains
21ca0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74  .**          not
21cb0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
21cc0 77 68 69 74 65 73 70 61 63 65 20 6f 72 20 63 6f  whitespace or co
21cd0 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  mments..**.** {H
21ce0 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69  13019} The [sqli
21cf0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
21d00 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20  ] interface and 
21d10 69 74 73 20 76 61 72 69 61 6e 74 73 20 72 65 74  its variants ret
21d20 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
21d30 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61  [SQLITE_OK] or a
21d40 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
21d50 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20  rror code] upon 
21d60 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b  failure..**.** {
21d70 48 31 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b  H13021} Before [
21d80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
21d90 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70  db,zSql,nByte,pp
21da0 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72  Stmt,pzTail)] or
21db0 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   its.**         
21dc0 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
21dd0 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20  s an error (any 
21de0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
21df0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a   [SQLITE_OK]),.*
21e00 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 79 20  *          they 
21e10 66 69 72 73 74 20 73 65 74 20 2a 70 70 53 74 6d  first set *ppStm
21e20 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  t to NULL..*/.in
21e30 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
21e40 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
21e50 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
21e60 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
21e70 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
21e80 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
21e90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
21ea0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
21eb0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
21ec0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
21ed0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
21ee0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
21ef0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
21f00 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
21f10 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
21f20 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
21f30 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
21f40 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
21f50 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
21f60 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
21f70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
21f80 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
21f90 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
21fa0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
21fb0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
21fc0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
21fd0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
21fe0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
21ff0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
22000 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
22010 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
22020 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
22030 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
22040 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
22050 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
22060 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
22070 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
22080 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
22090 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
220a0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
220b0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
220c0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
220d0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
220e0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
220f0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
22100 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
22110 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
22120 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
22130 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
22140 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
22150 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
22160 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
22170 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
22180 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
22190 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
221a0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
221b0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
221c0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
221d0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
221e0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
221f0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
22200 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
22210 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
22220 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
22230 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
22240 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
22250 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
22260 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
22270 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
22280 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
22290 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
222a0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
222b0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
222c0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
222d0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
222e0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
222f0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
22300 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
22310 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
22320 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
22330 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
22340 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
22350 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
22360 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20  g Statement SQL 
22370 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30  {H13100} <H13000
22380 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  >.**.** This int
22390 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
223a0 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
223b0 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
223c0 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
223d0 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
223e0 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
223f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
22400 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
22410 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
22420 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
22430 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
22440 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
22450 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
22460 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
22470 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 31  S:.**.** {H13101
22480 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72  } If the [prepar
22490 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61  ed statement] pa
224a0 73 73 65 64 20 61 73 20 74 68 65 20 61 72 67 75  ssed as the argu
224b0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  ment to.**      
224c0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c      [sqlite3_sql
224d0 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ()] was compiled
224e0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
224f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22500 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  2()] or.**      
22510 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
22520 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 74 68  pare16_v2()], th
22530 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28  en [sqlite3_sql(
22540 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  )] returns.**   
22550 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72         a pointer
22560 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
22570 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e  nated string con
22580 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20  taining a UTF-8 
22590 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20  rendering.**    
225a0 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69        of the ori
225b0 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d  ginal SQL statem
225c0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31  ent..**.** {H131
225d0 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70  02} If the [prep
225e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
225f0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72  passed as the ar
22600 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20  gument to.**    
22610 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
22620 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c  ql()] was compil
22630 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
22640 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22650 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
22660 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
22670 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 5b  are16()], then [
22680 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72  sqlite3_sql()] r
22690 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
226a0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  inter..**.** {H1
226b0 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e 67  3103} The string
226c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
226d0 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69 73  lite3_sql(S)] is
226e0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
226f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
22700 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22710 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64 20 75  ] S is deleted u
22720 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
22730 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63  nalize(S)]..*/.c
22740 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
22750 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
22760 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
22770 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
22780 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
22790 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48 31  Value Object {H1
227a0 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  5000} <S20200>.*
227b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
227c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
227d0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
227e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
227f0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
22800 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
22810 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
22820 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
22830 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
22840 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
22850 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
22860 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
22870 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
22880 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
22890 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20 73  stores. Values s
228a0 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
228b0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
228c0 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
228d0 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
228e0 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
228f0 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
22900 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
22910 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
22920 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
22930 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
22940 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
22950 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
22960 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
22970 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
22980 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
22990 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
229a0 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
229b0 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
229c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
229d0 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
229e0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
229f0 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
22a00 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
22a10 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
22a20 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
22a30 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
22a40 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
22a50 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
22a60 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
22a70 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
22a80 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
22a90 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
22aa0 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20  tex is held.  A 
22ab0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
22ac0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
22ad0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
22ae0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
22af0 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
22b00 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
22b10 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
22b20 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
22b30 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
22b40 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
22b50 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
22b60 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
22b70 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
22b80 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
22b90 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
22ba0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
22bb0 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
22bc0 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
22bd0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
22be0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
22bf0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
22c00 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
22c10 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
22c20 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
22c30 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
22c40 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
22c50 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
22c60 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
22c70 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
22c80 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
22c90 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
22ca0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
22cb0 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
22cc0 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
22cd0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
22ce0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
22cf0 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
22d00 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
22d10 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  en between prote
22d20 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
22d30 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
22d40 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
22d50 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
22d60 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
22d70 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
22d80 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
22d90 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
22da0 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
22db0 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
22dc0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
22dd0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
22de0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
22df0 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
22e00 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
22e10 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
22e20 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
22e30 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
22e40 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
22e50 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
22e60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
22e70 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
22e80 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
22e90 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
22ea0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
22eb0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
22ec0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
22ed0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
22ee0 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
22ef0 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
22f00 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
22f10 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
22f20 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
22f30 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
22f40 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
22f50 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
22f60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
22f70 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
22f80 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36 30  ext Object {H160
22f90 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  01} <S20200>.**.
22fa0 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
22fb0 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
22fc0 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
22fd0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
22fe0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
22ff0 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70  ext object.  A p
23000 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
23010 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
23020 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
23030 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
23040 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
23050 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
23060 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
23070 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
23080 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
23090 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
230a0 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
230b0 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
230c0 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
230d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
230e0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
230f0 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
23100 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
23110 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
23120 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
23130 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
23140 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
23150 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
23160 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
23170 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
23180 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
23190 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
231a0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
231b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
231c0 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
231d0 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
231e0 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
231f0 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30  tatements {H1350
23200 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b  0} <S70300>.** K
23210 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
23220 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
23230 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
23240 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
23250 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
23260 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
23270 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
23280 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
23290 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ng}.**.** In the
232a0 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70   SQL strings inp
232b0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
232c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
232d0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
232e0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
232f0 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
23300 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65  parameter in one
23310 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a   of these forms:
23320 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
23330 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
23340 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
23350 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
23360 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
23370 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
23380 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66   the parameter f
23390 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  orms shown above
233a0 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67   NNN is an integ
233b0 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
233c0 6e 64 20 56 56 56 20 69 73 20 61 6e 20 61 6c 70  nd VVV is an alp
233d0 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d  ha-numeric param
233e0 65 74 65 72 20 6e 61 6d 65 2e 20 54 68 65 20 76  eter name. The v
233f0 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
23400 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
23410 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
23420 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
23430 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
23440 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
23450 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
23460 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
23470 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
23480 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  here..**.** The 
23490 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
234a0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
234b0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
234c0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
234d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
234e0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
234f0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
23500 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
23510 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
23520 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
23530 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
23540 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
23550 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
23560 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
23570 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d  et..** The leftm
23580 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
23590 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
235a0 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73  f 1.  When the s
235b0 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
235c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
235d0 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
235e0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
235f0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
23600 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
23610 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
23620 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
23630 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65  nce..** The inde
23640 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
23650 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
23660 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
23670 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
23680 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
23690 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
236a0 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78  ired.  The index
236b0 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
236c0 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
236d0 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
236e0 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20  * The NNN value 
236f0 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
23700 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
23710 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
23720 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
23730 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
23740 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
23750 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
23760 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
23770 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
23780 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
23790 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
237a0 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75  .** In those rou
237b0 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
237c0 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
237d0 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
237e0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
237f0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
23800 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
23810 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
23820 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
23830 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
23840 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
23850 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
23860 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
23870 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
23880 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
23890 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68  tive, the length
238a0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
238b0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
238c0 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
238d0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
238e0 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
238f0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
23900 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
23910 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
23920 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
23930 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
23940 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
23950 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
23960 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
23970 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
23980 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
23990 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
239a0 77 69 74 68 20 69 74 2e 20 49 66 20 74 68 65 20  with it. If the 
239b0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
239c0 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
239d0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
239e0 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
239f0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
23a00 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
23a10 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
23a20 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
23a30 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
23a40 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
23a50 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74 68  .** If the fifth
23a60 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
23a70 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
23a80 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
23a90 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
23aa0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
23ab0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
23ac0 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
23ad0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
23ae0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
23af0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
23b00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23b10 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
23b20 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
23b30 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
23b40 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
23b50 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
23b60 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65    A zeroblob use
23b70 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
23b80 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
23b90 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
23ba0 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
23bb0 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
23bc0 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
23bd0 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
23be0 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
23bf0 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
23c00 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
23c10 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
23c20 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
23c30 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
23c40 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
23c50 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
23c60 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20   routines..** A 
23c70 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
23c80 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
23c90 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
23ca0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
23cb0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23cc0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
23cd0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
23ce0 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69  d after.** [sqli
23cf0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
23d00 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69 61  ] (and its varia
23d10 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33  nts) or [sqlite3
23d20 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a  _reset()] and.**
23d30 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33   before [sqlite3
23d40 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e  _step()]..** Bin
23d50 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
23d60 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
23d70 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
23d80 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75  outine..** Unbou
23d90 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
23da0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
23db0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
23dc0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
23dd0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
23de0 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20  n success or an 
23df0 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a  error code if.**
23e00 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
23e10 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52  rong.  [SQLITE_R
23e20 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
23e30 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
23e40 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
23e50 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53  ut of range.  [S
23e60 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
23e70 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
23e80 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b  oc() fails..** [
23e90 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
23ea0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
23eb0 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   if these routin
23ec0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e  es are called on
23ed0 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61   a.** virtual ma
23ee0 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74 68  chine that is th
23ef0 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72  e wrong state or
23f00 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65 61   which has alrea
23f10 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  dy been finalize
23f20 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20  d..** Detection 
23f30 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72  of misuse is unr
23f40 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63  eliable.  Applic
23f50 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
23f60 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53  t depend.** on S
23f70 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74  QLITE_MISUSE ret
23f80 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49  urns.  SQLITE_MI
23f90 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64  SUSE is intended
23fa0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a   to indicate a.*
23fb0 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  * a logic error 
23fc0 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  in the applicati
23fd0 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  on.  Future vers
23fe0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
23ff0 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61  ight.** panic ra
24000 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e  ther than return
24010 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
24020 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
24030 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
24040 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
24050 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
24060 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
24070 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
24080 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
24090 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a  r_index()]..**.*
240a0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
240b0 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54 68 65  .** {H13506} The
240c0 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   [SQL statement 
240d0 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e  compiler] recogn
240e0 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66 20 74  izes tokens of t
240f0 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 20 20  he forms.**     
24100 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22       "?", "?NNN"
24110 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22  , "$VVV", ":VVV"
24120 2c 20 61 6e 64 20 22 40 56 56 56 22 20 61 73 20  , and "@VVV" as 
24130 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2c 0a  SQL parameters,.
24140 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72  **          wher
24150 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71  e NNN is any seq
24160 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20  uence of one or 
24170 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a 20 20  more digits.**  
24180 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 72          and wher
24190 65 20 56 56 56 20 69 73 20 61 6e 79 20 73 65 71  e VVV is any seq
241a0 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20  uence of one or 
241b0 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65 72 69  more alphanumeri
241c0 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68  c.**          ch
241d0 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22  aracters or "::"
241e0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c   optionally foll
241f0 6f 77 65 64 20 62 79 20 61 20 73 74 72 69 6e 67  owed by a string
24200 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20   containing.**  
24210 20 20 20 20 20 20 20 20 6e 6f 20 73 70 61 63 65          no space
24220 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20  s and contained 
24230 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73  within parenthes
24240 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30  es..**.** {H1350
24250 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76  9} The initial v
24260 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70  alue of an SQL p
24270 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
24280 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 32 7d  ..**.** {H13512}
24290 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
242a0 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74   "?" SQL paramet
242b0 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72  er is one larger
242c0 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20   than the.**    
242d0 20 20 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e        largest in
242e0 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d  dex of SQL param
242f0 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74  eter to the left
24300 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20  , or 1 if.**    
24310 20 20 20 20 20 20 74 68 65 20 22 3f 22 20 69 73        the "?" is
24320 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51   the leftmost SQ
24330 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  L parameter..**.
24340 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54 68 65 20  ** {H13515} The 
24350 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e  index of an "?NN
24360 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  N" SQL parameter
24370 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72 20   is the integer 
24380 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  NNN..**.** {H135
24390 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  18} The index of
243a0 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56   an ":VVV", "$VV
243b0 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51  V", or "@VVV" SQ
243c0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  L parameter is.*
243d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
243e0 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65 78  ame as the index
243f0 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63   of leftmost occ
24400 75 72 72 65 6e 63 65 73 20 6f 66 20 74 68 65 20  urrences of the 
24410 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
24420 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f   parameter, or o
24430 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65  ne more than the
24440 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
24450 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ver all.**      
24460 20 20 20 20 70 61 72 61 6d 65 74 65 72 73 20 74      parameters t
24470 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20 74 68  o the left if th
24480 69 73 20 69 73 20 74 68 65 20 66 69 72 73 74 20  is is the first 
24490 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20  occurrence.**   
244a0 20 20 20 20 20 20 20 6f 66 20 74 68 69 73 20 70         of this p
244b0 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69  arameter, or 1 i
244c0 66 20 74 68 69 73 20 69 73 20 74 68 65 20 6c 65  f this is the le
244d0 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72  ftmost parameter
244e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 31 7d  ..**.** {H13521}
244f0 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d   The [SQL statem
24500 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61  ent compiler] fa
24510 69 6c 73 20 77 69 74 68 20 61 6e 20 5b 53 51 4c  ils with an [SQL
24520 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20 20  ITE_RANGE].**   
24530 20 20 20 20 20 20 20 65 72 72 6f 72 20 69 66 20         error if 
24540 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
24550 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
24560 20 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a 2a 20   less than 1.** 
24570 20 20 20 20 20 20 20 20 20 6f 72 20 67 72 65 61           or grea
24580 74 65 72 20 74 68 61 6e 20 74 68 65 20 63 6f 6d  ter than the com
24590 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49 54 45  pile-time SQLITE
245a0 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55  _MAX_VARIABLE_NU
245b0 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20 20 20 20  MBER.**         
245c0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
245d0 2a 20 7b 48 31 33 35 32 34 7d 20 43 61 6c 6c 73  * {H13524} Calls
245e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
245f0 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
24600 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29  _bind(S,N,V,...)
24610 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  ].**          as
24620 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c 75  sociate the valu
24630 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51 4c  e V with all SQL
24640 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76 69   parameters havi
24650 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ng an.**        
24660 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e 20    index of N in 
24670 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24680 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
24690 2a 20 7b 48 31 33 35 32 37 7d 20 43 61 6c 6c 73  * {H13527} Calls
246a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
246b0 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33  d_text | sqlite3
246c0 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a  _bind(S,N,...)].
246d0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72  **          over
246e0 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c 73  ride prior calls
246f0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76   with the same v
24700 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20 4e  alues of S and N
24710 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 30 7d  ..**.** {H13530}
24720 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62 6c   Bindings establ
24730 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74 65  ished by [sqlite
24740 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
24750 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e  lite3_bind(S,...
24760 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  )].**          p
24770 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63 61  ersist across ca
24780 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
24790 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a  reset(S)]..**.**
247a0 20 7b 48 31 33 35 33 33 7d 20 49 6e 20 63 61 6c   {H13533} In cal
247b0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
247c0 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
247d0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
247e0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
247f0 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
24800 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
24810 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
24820 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
24830 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 74  ] SQLite binds t
24840 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20 20  he first L.**   
24850 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66 20         bytes of 
24860 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
24870 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
24880 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20 20   V, when L.**   
24890 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e 65         is non-ne
248a0 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
248b0 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73 20  13536} In calls 
248c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
248d0 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
248e0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
248f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
24900 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
24910 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 63  ] SQLite binds c
24920 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20 20  haracters.**    
24930 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68 72        from V thr
24940 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
24950 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77 68  ero character wh
24960 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65  en L is negative
24970 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 39 7d  ..**.** {H13539}
24980 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
24990 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
249a0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
249b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
249c0 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
249d0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
249e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
249f0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
24a00 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
24a10 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a  is the special.*
24a20 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  *          const
24a30 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  ant [SQLITE_STAT
24a40 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73 75  IC], SQLite assu
24a50 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61 6c  mes that the val
24a60 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20 20  ue V.**         
24a70 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61 74   is held in stat
24a80 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  ic unmanaged spa
24a90 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f 74  ce that will not
24aa0 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20   change.**      
24ab0 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20 6c      during the l
24ac0 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 62  ifetime of the b
24ad0 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  inding..**.** {H
24ae0 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73 20  13542} In calls 
24af0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
24b00 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _blob(S,N,V,L,D)
24b10 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
24b20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
24b30 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f  t(S,N,V,L,D)], o
24b40 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
24b50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24b60 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77  16(S,N,V,L,D)] w
24b70 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65  hen D is the spe
24b80 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  cial.**         
24b90 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54   constant [SQLIT
24ba0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
24bb0 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20  e routine makes 
24bc0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  a.**          pr
24bd0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
24be0 65 20 76 61 6c 75 65 20 56 20 62 65 66 6f 72 65  e value V before
24bf0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
24c00 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e 20 63  ** {H13545} In c
24c10 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
24c20 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56  _bind_blob(S,N,V
24c30 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,L,D)],.**      
24c40 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
24c50 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
24c60 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
24c70 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
24c80 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
24c90 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20  D)] when D is a 
24ca0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20  pointer to.**   
24cb0 20 20 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f         a functio
24cc0 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  n, SQLite invoke
24cd0 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  s that function 
24ce0 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a  to destroy the.*
24cf0 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
24d00 20 56 20 61 66 74 65 72 20 69 74 20 68 61 73 20   V after it has 
24d10 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
24d20 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  he value V..**.*
24d30 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e 20 63 61  * {H13548} In ca
24d40 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
24d50 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c  bind_zeroblob(S,
24d60 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75  N,V,L)] the valu
24d70 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20  e bound.**      
24d80 20 20 20 20 69 73 20 61 20 42 4c 4f 42 20 6f 66      is a BLOB of
24d90 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a   L bytes, or a z
24da0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
24db0 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65  if L is negative
24dc0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35 31 7d  ..**.** {H13551}
24dd0 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
24de0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
24df0 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61  (S,N,V)] the V a
24e00 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20  rgument may.**  
24e10 20 20 20 20 20 20 20 20 62 65 20 65 69 74 68 65          be eithe
24e20 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73  r a [protected s
24e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
24e40 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20  ject or an.**   
24e50 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63         [unprotec
24e60 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
24e70 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e  e] object..*/.in
24e80 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
24e90 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
24ea0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
24eb0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
24ec0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
24ed0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
24ee0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
24ef0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
24f00 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
24f10 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
24f20 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
24f30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
24f40 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
24f50 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
24f60 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
24f70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
24f80 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
24f90 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
24fa0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
24fb0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
24fc0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
24fd0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
24fe0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
24ff0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
25000 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25010 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
25020 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
25030 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
25040 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
25050 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
25060 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
25070 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
25080 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
25090 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
250a0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
250b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
250c0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
250d0 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d 20  meters {H13600} 
250e0 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70300>.**.** T
250f0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
25100 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
25110 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
25120 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
25130 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
25140 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
25150 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
25160 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
25170 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
25180 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
25190 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
251a0 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
251b0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
251c0 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
251d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
251e0 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
251f0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
25200 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
25210 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
25220 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
25230 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
25240 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
25250 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
25260 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
25270 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
25280 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
25290 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
252a0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
252b0 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
252c0 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
252d0 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75  f the ?NNN are u
252e0 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
252f0 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
25300 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   list..**.** See
25310 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
25320 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
25330 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
25340 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
25350 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
25360 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
25370 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
25380 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
25390 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
253a0 7b 48 31 33 36 30 31 7d 20 54 68 65 20 5b 73 71  {H13601} The [sq
253b0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
253c0 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69  eter_count(S)] i
253d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
253e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
253f0 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f   largest index o
25400 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65  f all SQL parame
25410 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ters in the.**  
25420 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
25430 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20  d statement] S, 
25440 6f 72 20 30 20 69 66 20 53 20 63 6f 6e 74 61 69  or 0 if S contai
25450 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65  ns no SQL parame
25460 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ters..*/.int sql
25470 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
25480 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
25490 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
254a0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
254b0 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
254c0 74 65 72 20 7b 48 31 33 36 32 30 7d 20 3c 53 37  ter {H13620} <S7
254d0 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0300>.**.** This
254e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
254f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
25500 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d  e name of the n-
25510 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d  th.** [SQL param
25520 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72 65 70  eter] in a [prep
25530 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
25540 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
25550 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
25560 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
25570 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
25580 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
25590 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
255a0 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
255b0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
255c0 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
255d0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
255e0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
255f0 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
25600 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
25610 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
25620 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
25630 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61  he name..** Para
25640 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
25650 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
25660 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
25670 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
25680 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 6f 20  ** and are also 
25690 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
256a0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
256b0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ters"..**.** The
256c0 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
256d0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
256e0 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
256f0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c  **.** If the val
25700 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue n is out of r
25710 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e  ange or if the n
25720 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
25730 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
25740 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
25750 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e  ned.  The return
25760 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
25770 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
25780 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
25790 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
257a0 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
257b0 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
257c0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
257d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
257e0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
257f0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
25800 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
25810 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
25820 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
25830 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
25840 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25850 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
25860 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
25870 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
25880 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
25890 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
258a0 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  13621} The [sqli
258b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
258c0 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  er_name(S,N)] in
258d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
258e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 55 54  **          a UT
258f0 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
25900 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25910 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
25920 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
25930 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25940 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67 20  ement] S having 
25950 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20  index N, or.**  
25960 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66 20          NULL if 
25970 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c 20  there is no SQL 
25980 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69  parameter with i
25990 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68 65  ndex N or if the
259a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
259b0 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65  ameter with inde
259c0 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d  x N is an anonym
259d0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20 22 3f  ous parameter "?
259e0 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  "..*/.const char
259f0 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
25a00 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
25a10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25a20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25a30 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
25a40 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
25a50 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36  Given Name {H136
25a60 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a  40} <S70300>.**.
25a70 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e  ** Return the in
25a80 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
25a90 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
25aa0 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20  s name.  The.** 
25ab0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
25ac0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
25ad0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
25ae0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
25af0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
25b00 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
25b10 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65  3_bind()].  A ze
25b20 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
25b30 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
25b40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
25b50 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65  und.  The parame
25b60 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
25b70 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
25b80 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
25b90 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
25ba0 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
25bb0 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
25bc0 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
25bd0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
25be0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
25bf0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
25c00 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
25c10 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
25c20 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
25c30 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
25c40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
25c50 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
25c60 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
25c70 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
25c80 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3641} The [sqlit
25c90 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
25ca0 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e  r_index(S,N)] in
25cb0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
25cc0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
25cd0 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72  index of SQL par
25ce0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 5b 70  ameter in the [p
25cf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25d00 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  t].**          S
25d10 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63   whose name matc
25d20 68 65 73 20 74 68 65 20 55 54 46 2d 38 20 73 74  hes the UTF-8 st
25d30 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66 20  ring N, or 0 if 
25d40 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 20 20  there is.**     
25d50 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a       no match..*
25d60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
25d70 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
25d80 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
25d90 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
25da0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
25db0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
25dc0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
25dd0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
25de0 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 33  t {H13660} <S703
25df0 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61  00>.**.** Contra
25e00 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
25e10 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
25e20 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
25e30 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
25e40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
25e50 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
25e60 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
25e70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
25e80 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69  * Use this routi
25e90 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
25ea0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
25eb0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49  to NULL..**.** I
25ec0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
25ed0 20 7b 48 31 33 36 36 31 7d 20 54 68 65 20 5b 73   {H13661} The [s
25ee0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
25ef0 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66  dings(S)] interf
25f00 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20 53  ace resets all S
25f10 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  QL.**          p
25f20 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
25f30 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  s in the [prepar
25f40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25f50 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  back to NULL..*/
25f60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
25f70 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
25f80 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
25f90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
25fa0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
25fb0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
25fc0 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30 3e  H13710} <S10700>
25fd0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68  .**.** Return th
25fe0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
25ff0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
26000 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
26010 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
26020 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54  ed statement]. T
26030 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
26040 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69  rns 0 if pStmt i
26050 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74  s an SQL.** stat
26060 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20  ement that does 
26070 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20  not return data 
26080 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
26090 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a  [UPDATE])..**.**
260a0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
260b0 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54 68 65 20  ** {H13711} The 
260c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
260d0 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66  count(S)] interf
260e0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
260f0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20  number of.**    
26100 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69 6e        columns in
26110 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
26120 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68 65  generated by the
26130 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26140 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20  ment] S,.**     
26150 20 20 20 20 20 6f 72 20 30 20 69 66 20 53 20 64       or 0 if S d
26160 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74 65  oes not generate
26170 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a   a result set..*
26180 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
26190 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
261a0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
261b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
261c0 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
261d0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b  n A Result Set {
261e0 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30 3e  H13720} <S10700>
261f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
26200 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
26210 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
26220 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
26230 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
26240 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
26250 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
26260 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  nt.  The sqlite3
26270 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
26280 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
26290 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
262a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
262b0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
262c0 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
262d0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
262e0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
262f0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
26300 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
26310 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72  string.  The fir
26320 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
26330 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
26340 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
26350 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
26360 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
26370 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  nt. The second p
26380 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
26390 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
263a0 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  .  The leftmost 
263b0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
263c0 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65   0..**.** The re
263d0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
263e0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
263f0 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
26400 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26410 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
26420 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
26430 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
26440 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
26450 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
26460 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
26470 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
26480 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
26490 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
264a0 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  *.** If sqlite3_
264b0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
264c0 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
264d0 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
264e0 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
264f0 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
26500 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
26510 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
26520 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
26530 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
26540 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  ned..**.** The n
26550 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  ame of a result 
26560 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61  column is the va
26570 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20  lue of the "AS" 
26580 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  clause for.** th
26590 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68  at column, if th
265a0 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61  ere is an AS cla
265b0 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69  use.  If there i
265c0 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a  s no AS clause.*
265d0 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20  * then the name 
265e0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
265f0 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64   unspecified and
26600 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
26610 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  .** one release 
26620 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  of SQLite to the
26630 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   next..**.** INV
26640 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
26650 48 31 33 37 32 31 7d 20 41 20 73 75 63 63 65 73  H13721} A succes
26660 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
26670 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
26680 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29  column_name(S,N)
26690 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
266a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
266b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
266c0 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72  Nth column (wher
266d0 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  e 0 is.**       
266e0 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20     the leftmost 
266f0 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20  column) for the 
26700 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
26710 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
26720 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26730 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74  t] S as a zero-t
26740 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
26750 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
26760 31 33 37 32 33 7d 20 41 20 73 75 63 63 65 73 73  13723} A success
26770 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
26780 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
26790 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e  olumn_name16(S,N
267a0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
267b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
267c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
267d0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65   Nth column (whe
267e0 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20  re 0 is.**      
267f0 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74      the leftmost
26800 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65   column) for the
26810 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
26820 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
26830 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26840 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d  nt] S as a zero-
26850 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31  terminated UTF-1
26860 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  6 string.**     
26870 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69       in the nati
26880 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
26890 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20 54 68  *.** {H13724} Th
268a0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
268b0 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73  n_name()] and [s
268c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
268d0 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  me16()].**      
268e0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72      interfaces r
268f0 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  eturn a NULL poi
26900 6e 74 65 72 20 69 66 20 74 68 65 79 20 61 72 65  nter if they are
26910 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20   unable to.**   
26920 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20         allocate 
26930 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
26940 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75  heir normal retu
26950 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a  rn strings..**.*
26960 2a 20 7b 48 31 33 37 32 35 7d 20 49 66 20 74 68  * {H13725} If th
26970 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
26980 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26990 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a  _name(S,N)] or.*
269a0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
269b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
269c0 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f  6(S,N)] is out o
269d0 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68  f range, then th
269e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
269f0 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
26a00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
26a10 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d 20 54  **.** {H13726} T
26a20 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
26a30 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
26a40 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29  column_name(S,N)
26a50 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
26a60 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
26a70 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61  n_name16(S,N)] a
26a80 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  re valid until t
26a90 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20  he next.**      
26aa0 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74 68      call to eith
26ab0 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  er routine with 
26ac0 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20 4e  the same S and N
26ad0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20   parameters.**  
26ae0 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c          or until
26af0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
26b00 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
26b10 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 37 7d  ..**.** {H13727}
26b20 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20 63   When a result c
26b30 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45  olumn of a [SELE
26b40 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  CT] statement co
26b50 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ntains.**       
26b60 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2c     an AS clause,
26b70 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61   the name of tha
26b80 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
26b90 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20  identifier.**   
26ba0 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 72 69         to the ri
26bb0 67 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b 65  ght of the AS ke
26bc0 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  yword..*/.const 
26bd0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
26be0 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  lumn_name(sqlite
26bf0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
26c00 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
26c10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26c20 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
26c30 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int N);../*.**
26c40 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63   CAPI3REF: Sourc
26c50 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51  e Of Data In A Q
26c60 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33  uery Result {H13
26c70 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  740} <S10700>.**
26c80 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
26c90 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
26ca0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
26cb0 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77  what column of w
26cc0 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20  hat.** table in 
26cd0 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61  which database a
26ce0 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53 45   result of a [SE
26cf0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
26d00 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54  comes from..** T
26d10 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
26d20 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65  atabase or table
26d30 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62   or column can b
26d40 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a  e returned as.**
26d50 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20   either a UTF-8 
26d60 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
26d70 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65  .  The _database
26d80 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
26d90 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
26da0 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
26db0 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
26dc0 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
26dd0 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
26de0 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
26df0 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
26e00 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72  n name..** The r
26e10 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
26e20 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
26e30 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
26e40 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
26e50 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
26e60 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
26e70 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
26e80 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
26e90 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
26ea0 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
26eb0 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
26ec0 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72  *.** The names r
26ed0 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
26ee0 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
26ef0 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
26f00 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
26f10 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
26f20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
26f30 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
26f40 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73   following calls
26f50 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
26f60 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54  statement]..** T
26f70 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
26f80 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
26f90 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
26fa0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
26fb0 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
26fc0 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
26fd0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
26fe0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
26ff0 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63  .** If the Nth c
27000 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
27010 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
27020 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
27030 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
27040 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
27050 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
27060 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
27070 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
27080 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f   NULL.  These ro
27090 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
270a0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
270b0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
270c0 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
270d0 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  urs.  Otherwise,
270e0 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
270f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
27100 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
27110 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c  table.** and col
27120 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
27130 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
27140 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
27150 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61  .**.** As with a
27160 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
27170 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74  APIs, those post
27180 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20  fixed with "16" 
27190 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
271a0 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
271b0 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  , the other func
271c0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
271d0 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  -8. {END}.**.** 
271e0 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
271f0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
27200 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
27210 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
27220 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
27230 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
27240 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
27250 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
27260 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37  ned..**.** {A137
27270 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  51}.** If two or
27280 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
27290 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
272a0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
272b0 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
272c0 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
272d0 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
272e0 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
272f0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
27300 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
27310 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  fined..**.** INV
27320 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
27330 48 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71 6c  H13741} The [sql
27340 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
27350 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  base_name(S,N)] 
27360 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27370 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
27380 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a       the UTF-8 z
27390 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
273a0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
273b0 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ase from which t
273c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
273d0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
273e0 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
273f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
27400 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20  s extracted,.** 
27410 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
27420 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
27430 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
27440 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
27450 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
27460 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
27470 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
27480 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
27490 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20 54 68  *.** {H13742} Th
274a0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
274b0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
274c0 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
274d0 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
274e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
274f0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
27500 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74  yte order zero-t
27510 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
27520 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
27530 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
27540 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65  which the Nth re
27550 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
27560 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
27570 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20  tement] S is.** 
27580 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63 74           extract
27590 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  ed, or NULL if t
275a0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
275b0 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
275c0 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
275d0 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
275e0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
275f0 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
27600 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
27610 7b 48 31 33 37 34 33 7d 20 54 68 65 20 5b 73 71  {H13743} The [sq
27620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
27630 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  le_name(S,N)] in
27640 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27650 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
27660 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72     the UTF-8 zer
27670 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
27680 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66  e of the table f
27690 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a  rom which the.**
276a0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
276b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
276c0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
276d0 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74  tement] S is ext
276e0 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20  racted,.**      
276f0 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74      or NULL if t
27700 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
27710 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
27720 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
27730 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
27740 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
27750 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
27760 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
27770 7b 48 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71  {H13744} The [sq
27780 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
27790 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  le_name16(S,N)] 
277a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
277b0 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
277c0 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20       the UTF-16 
277d0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
277e0 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  r zero-terminate
277f0 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
27800 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
27810 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e  from which the N
27820 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
27830 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
27840 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
27850 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
27860 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
27870 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
27880 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
27890 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
278a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
278b0 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
278c0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
278d0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
278e0 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20 54 68  *.** {H13745} Th
278f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
27900 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c  n_origin_name(S,
27910 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
27920 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
27930 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
27940 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
27950 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
27960 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d  able column from
27970 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20   which the.**   
27980 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c         Nth resul
27990 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
279a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
279b0 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63  ent] S is extrac
279c0 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted,.**         
279d0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
279e0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
279f0 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70  is a general exp
27a00 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  ression.**      
27a10 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65      or if unable
27a20 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
27a30 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65  ory to store the
27a40 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   name..**.** {H1
27a50 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  3746} The [sqlit
27a60 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
27a70 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e  _name16(S,N)] in
27a80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27a90 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
27aa0 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61     the UTF-16 na
27ab0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
27ac0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
27ad0 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
27ae0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
27af0 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20  lumn from which 
27b00 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
27b10 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
27b20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
27b30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
27b40 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72  is extracted, or
27b50 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
27b60 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20   column.**      
27b70 20 20 20 20 6f 66 20 53 20 69 73 20 61 20 67 65      of S is a ge
27b80 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
27b90 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
27ba0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
27bb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
27bc0 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
27bd0 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d 20 54  **.** {H13748} T
27be0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  he return values
27bf0 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20   from.**        
27c00 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
27c10 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
27c20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
27c30 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
27c40 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61            are va
27c50 6c 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66 65  lid for the life
27c60 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65  time of the [pre
27c70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27c80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
27c90 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69  until the encodi
27ca0 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20 62 79  ng is changed by
27cb0 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74   another metadat
27cc0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  a.**          in
27cd0 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72  terface call for
27ce0 20 74 68 65 20 73 61 6d 65 20 70 72 65 70 61 72   the same prepar
27cf0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
27d00 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 41   column..**.** A
27d10 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
27d20 2a 20 7b 41 31 33 37 35 31 7d 20 49 66 20 74 77  * {A13751} If tw
27d30 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
27d40 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
27d50 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  re.**          [
27d60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
27d70 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
27d80 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
27d90 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20  nterfaces].**   
27da0 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 73         for the s
27db0 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
27dc0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
27dd0 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20  ult column.**   
27de0 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73 61         at the sa
27df0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
27e00 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
27e10 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
27e20 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
27e30 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
27e40 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
27e50 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
27e60 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
27e70 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
27e80 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
27e90 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
27ea0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
27eb0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
27ec0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
27ed0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
27ee0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
27ef0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
27f00 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
27f10 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27f20 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
27f30 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
27f40 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
27f50 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
27f60 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
27f70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
27f80 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
27f90 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
27fa0 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
27fb0 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 36  ry Result {H1376
27fc0 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
27fd0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
27fe0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
27ff0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
28000 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
28010 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
28020 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
28030 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
28040 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
28050 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
28060 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
28070 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
28080 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
28090 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
280a0 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
280b0 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
280c0 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
280d0 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  mn is returned. 
280e0 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   If the Nth colu
280f0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
28100 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
28110 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
28120 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
28130 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
28140 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65  urned..** The re
28150 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
28160 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
28170 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  coded. {END}.**.
28180 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
28190 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
281a0 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
281b0 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
281c0 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
281d0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
281e0 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
281f0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
28200 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
28210 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
28220 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
28230 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
28240 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
28250 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
28260 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
28270 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
28280 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
28290 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
282a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
282b0 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  =0)..**.** SQLit
282c0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
282d0 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
282e0 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65   So just because
282f0 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
28300 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
28310 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
28320 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
28330 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
28340 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
28350 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
28360 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
28370 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
28380 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
28390 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
283a0 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
283b0 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a  static.  Type.**
283c0 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
283d0 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
283e0 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
283f0 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
28400 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
28410 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a  hose values..**.
28420 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
28430 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20 20 41  *.** {H13761}  A
28440 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
28450 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
28460 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e  umn_decltype(S,N
28470 29 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20  )] returns a.** 
28480 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74            zero-t
28490 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
284a0 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
284b0 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64  g the declared d
284c0 61 74 61 74 79 70 65 0a 2a 2a 20 20 20 20 20 20  atatype.**      
284d0 20 20 20 20 20 6f 66 20 74 68 65 20 74 61 62 6c       of the tabl
284e0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70  e column that ap
284f0 70 65 61 72 73 20 61 73 20 74 68 65 20 4e 74 68  pears as the Nth
28500 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65   column (numbere
28510 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66  d.**           f
28520 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65  rom 0) of the re
28530 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 20  sult set to the 
28540 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28550 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ent] S..**.** {H
28560 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 65 73  13762}  A succes
28570 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
28580 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
28590 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a  ltype16(S,N)].**
285a0 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
285b0 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ns a zero-termin
285c0 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  ated UTF-16 nati
285d0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74  ve byte order st
285e0 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
285f0 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65    containing the
28600 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79   declared dataty
28610 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  pe of the table 
28620 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65  column that appe
28630 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ars.**          
28640 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   as the Nth colu
28650 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f  mn (numbered fro
28660 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75  m 0) of the resu
28670 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a  lt set to the.**
28680 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70             [prep
28690 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
286a0 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 33  S..**.** {H13763
286b0 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20  }  If N is less 
286c0 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20 67  than 0 or N is g
286d0 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65  reater than or e
286e0 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20  qual to.**      
286f0 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72 20       the number 
28700 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
28710 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28720 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20  ement] S,.**    
28730 20 20 20 20 20 20 20 6f 72 20 69 66 20 74 68 65         or if the
28740 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53   Nth column of S
28750 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
28760 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20 72 61  n or subquery ra
28770 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
28780 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20 63    than a table c
28790 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61 20 6d  olumn, or if a m
287a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
287b0 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20   failure.**     
287c0 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72        occurs dur
287d0 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e  ing encoding con
287e0 76 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a  versions, then.*
287f0 2a 20 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  *           call
28800 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  s to [sqlite3_co
28810 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c  lumn_decltype(S,
28820 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  N)] or.**       
28830 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
28840 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53  umn_decltype16(S
28850 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c  ,N)] return NULL
28860 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
28870 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
28880 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
28890 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
288a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
288b0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
288c0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
288d0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
288e0 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
288f0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
28900 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 30  t {H13200} <S100
28910 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  00>.**.** After 
28920 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
28930 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
28940 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
28950 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
28960 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
28970 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
28980 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
28990 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
289a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
289b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
289c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
289d0 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
289e0 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
289f0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
28a00 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
28a10 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
28a20 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
28a30 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
28a40 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
28a50 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
28a60 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
28a70 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
28a80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
28a90 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
28aa0 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
28ab0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
28ac0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28ad0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
28ae0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
28af0 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
28b00 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
28b10 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
28b20 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
28b30 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
28b40 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
28b50 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
28b60 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
28b70 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
28b80 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
28b90 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
28ba0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
28bb0 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
28bc0 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  orted..**.** In 
28bd0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
28be0 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
28bf0 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
28c00 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
28c10 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
28c20 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
28c30 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
28c40 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
28c50 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68  MISUSE]..** With
28c60 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
28c70 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
28c80 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
28c90 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
28ca0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
28cb0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
28cc0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
28cd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
28ce0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
28cf0 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
28d00 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
28d10 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
28d20 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
28d30 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
28d40 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61  job.  If the sta
28d50 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
28d60 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
28d70 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
28d80 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
28d90 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
28da0 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
28db0 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
28dc0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
28dd0 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
28de0 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
28df0 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
28e00 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
28e10 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
28e20 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
28e30 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
28e40 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
28e50 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
28e60 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
28e70 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
28e80 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
28e90 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
28ea0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
28eb0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
28ec0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
28ed0 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
28ee0 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
28ef0 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
28f00 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
28f10 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
28f20 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
28f30 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
28f40 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66   state..**.** If
28f50 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
28f60 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
28f70 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
28f80 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
28f90 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
28fa0 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
28fb0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
28fc0 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
28fd0 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
28fe0 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
28ff0 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
29000 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
29010 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
29020 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
29030 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
29040 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
29050 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
29060 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
29070 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  *.** [SQLITE_ERR
29080 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
29090 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
290a0 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
290b0 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
290c0 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
290d0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
290e0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
290f0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
29100 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
29110 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
29120 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
29130 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
29140 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20  msg()]..** With 
29150 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
29160 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
29170 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
29180 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
29190 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
291a0 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
291b0 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
291c0 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
291d0 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
291e0 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
291f0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
29200 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
29210 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29220 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22  ment].  In the "
29230 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
29240 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
29250 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
29260 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
29270 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
29280 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
29290 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
292a0 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
292b0 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
292c0 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
292d0 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
292e0 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
292f0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
29300 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
29310 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
29320 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
29330 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
29340 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
29350 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
29360 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
29370 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
29380 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
29390 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
293a0 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
293b0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
293c0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
293d0 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
293e0 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
293f0 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
29400 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
29410 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
29420 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
29430 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
29440 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
29450 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
29460 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
29470 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
29480 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
29490 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
294a0 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
294b0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
294c0 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
294d0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
294e0 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
294f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29500 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
29510 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
29520 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
29530 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
29540 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
29550 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
29560 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
29570 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
29580 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
29590 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
295a0 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
295b0 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
295c0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
295d0 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
295e0 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
295f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
29600 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
29610 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
29620 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
29630 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
29640 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
29650 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
29660 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
29670 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29680 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
29690 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
296a0 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
296b0 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
296c0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
296d0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
296e0 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
296f0 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
29700 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
29710 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  nded..**.** INVA
29720 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
29730 31 33 32 30 32 7d 20 20 49 66 20 74 68 65 20 5b  13202}  If the [
29740 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29750 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 20 74  nt] S is ready t
29760 6f 20 62 65 20 72 75 6e 2c 20 74 68 65 6e 0a 2a  o be run, then.*
29770 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
29780 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61 64  ite3_step(S)] ad
29790 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 65 70  vances that prep
297a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
297b0 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntil.**         
297c0 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20    completion or 
297d0 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61 64  until it is read
297e0 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74  y to return anot
297f0 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a  her row of the.*
29800 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 73 75  *           resu
29810 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 69 6c  lt set, or until
29820 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   an [sqlite3_int
29830 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75  errupt | interru
29840 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  pt].**          
29850 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65   or a run-time e
29860 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
29870 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20 57 68 65  ** {H15304}  Whe
29880 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  n a call to [sql
29890 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63 61  ite3_step(S)] ca
298a0 75 73 65 73 20 74 68 65 20 5b 70 72 65 70 61 72  uses the [prepar
298b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
298c0 20 20 20 20 20 20 20 20 20 20 20 53 20 74 6f 20             S to 
298d0 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
298e0 6e 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  n, the function 
298f0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
29900 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  DONE]..**.** {H1
29910 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63 61  5306}  When a ca
29920 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
29930 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62 65  tep(S)] stops be
29940 63 61 75 73 65 20 69 74 20 69 73 20 72 65 61 64  cause it is read
29950 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  y to.**         
29960 20 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72    return another
29970 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
29980 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 75 72  lt set, it retur
29990 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e  ns [SQLITE_ROW].
299a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38 7d 20  .**.** {H15308} 
299b0 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   If a call to [s
299c0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
299d0 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a  encounters an.**
299e0 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
299f0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20  te3_interrupt | 
29a00 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20  interrupt] or a 
29a10 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a  run-time error,.
29a20 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 20  **           it 
29a30 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
29a40 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f 64  priate error cod
29a50 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f 6e  e that is not on
29a60 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
29a70 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b    [SQLITE_OK], [
29a80 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72 20  SQLITE_ROW], or 
29a90 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a  [SQLITE_DONE]..*
29aa0 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20 20 49  *.** {H15310}  I
29ab0 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e  f an [sqlite3_in
29ac0 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
29ad0 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69  upt] or a run-ti
29ae0 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20  me error.**     
29af0 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72        occurs dur
29b00 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
29b10 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a  qlite3_step(S)].
29b20 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72  **           for
29b30 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
29b40 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65  tement] S create
29b50 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
29b60 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65       legacy inte
29b70 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
29b80 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a  prepare()] or.**
29b90 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
29ba0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
29bb0 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74  , then the funct
29bc0 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68  ion returns eith
29bd0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  er.**           
29be0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
29bf0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f  [SQLITE_BUSY], o
29c00 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
29c10 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
29c20 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
29c30 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
29c40 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
29c50 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
29c60 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37 37  esult set {H1377
29c70 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
29c80 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * Returns the nu
29c90 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69  mber of values i
29ca0 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
29cb0 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
29cc0 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  set..**.** INVAR
29cd0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
29ce0 33 37 37 31 7d 20 20 41 66 74 65 72 20 61 20 63  3771}  After a c
29cf0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
29d00 73 74 65 70 28 53 29 5d 20 74 68 61 74 20 72 65  step(S)] that re
29d10 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f  turns [SQLITE_RO
29d20 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  W],.**          
29d30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61   the [sqlite3_da
29d40 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75  ta_count(S)] rou
29d50 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
29d60 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 0a   the same value.
29d70 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20  **           as 
29d80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
29d90 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75  umn_count(S)] fu
29da0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nction..**.** {H
29db0 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b 73  13772}  After [s
29dc0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
29dd0 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e 79  has returned any
29de0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
29df0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  n.**           [
29e00 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62  SQLITE_ROW] or b
29e10 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73  efore [sqlite3_s
29e20 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65 6e  tep(S)] has been
29e30 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 0a 2a   called on the.*
29e40 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  *           [pre
29e50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29e60 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 74   for the first t
29e70 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73  ime since it was
29e80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
29e90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
29ea0 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20 5b 73   prepared] or [s
29eb0 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c 20 72  qlite3_reset | r
29ec0 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  eset],.**       
29ed0 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
29ee0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20  _data_count(S)] 
29ef0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
29f00 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  zero..*/.int sql
29f10 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
29f20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
29f30 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
29f40 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
29f50 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48 31  al Datatypes {H1
29f60 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53  0265} <S10110><S
29f70 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  10120>.** KEYWOR
29f80 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
29f90 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45  **.** {H10266} E
29fa0 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
29fb0 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
29fc0 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
29fd0 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
29fe0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
29ff0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2a000 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
2a010 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
2a020 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
2a030 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
2a040 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
2a050 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
2a060 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
2a070 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
2a080 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
2a090 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
2a0a0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2a0b0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
2a0c0 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
2a0d0 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
2a0e0 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
2a0f0 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
2a100 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
2a110 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
2a120 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
2a130 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
2a140 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
2a150 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
2a160 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
2a170 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
2a180 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
2a190 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
2a1a0 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
2a1b0 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
2a1c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a1d0 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
2a1e0 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
2a1f0 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
2a200 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
2a210 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
2a220 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
2a230 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
2a240 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
2a250 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
2a260 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a270 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
2a280 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33 38  om A Query {H138
2a290 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20  00} <S10700>.** 
2a2a0 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
2a2b0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2a2c0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2a2d0 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
2a2e0 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75  e "result set qu
2a2f0 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  ery" interface..
2a300 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2a310 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
2a320 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
2a330 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
2a340 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
2a350 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
2a360 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79  query.  In every
2a370 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
2a380 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2a390 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2a3a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a3b0 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
2a3c0 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
2a3d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
2a3e0 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
2a3f0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2a400 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a410 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
2a420 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
2a430 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
2a440 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2a450 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2a460 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
2a470 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
2a480 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54   be returned.  T
2a490 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2a4a0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2a4b0 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
2a4c0 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ex 0..**.** If t
2a4d0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2a4e0 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
2a4f0 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
2a500 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
2a510 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
2a520 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
2a530 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
2a540 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2a550 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2a560 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
2a570 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
2a580 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
2a590 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2a5a0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2a5b0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
2a5c0 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
2a5d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
2a5e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2a5f0 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
2a600 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
2a610 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
2a620 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2a630 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
2a640 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
2a650 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2a660 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2a670 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
2a680 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2a690 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
2a6a0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
2a6b0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
2a6c0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2a6d0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
2a6e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2a6f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2a700 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2a710 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
2a720 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
2a730 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
2a740 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
2a750 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2a760 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
2a770 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2a780 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2a790 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2a7a0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
2a7b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2a7c0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
2a7d0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2a7e0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
2a7f0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
2a800 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
2a810 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72  t column.  The r
2a820 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
2a830 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2a840 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
2a850 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
2a860 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
2a870 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
2a880 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
2a890 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
2a8a0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2a8b0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2a8c0 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
2a8d0 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
2a8e0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
2a8f0 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
2a900 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
2a910 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
2a920 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
2a930 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
2a940 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2a950 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
2a960 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
2a970 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2a980 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
2a990 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
2a9a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2a9b0 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
2a9c0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2a9d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72  ..**.** If the r
2a9e0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2a9f0 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
2aa00 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2aa10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
2aa20 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2aa30 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2aa40 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2aa50 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2aa60 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
2aa70 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
2aa80 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2aa90 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2aaa0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2aab0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
2aac0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
2aad0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2aae0 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ytes..** If the 
2aaf0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2ab00 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2ab10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ab20 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
2ab30 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2ab40 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2ab50 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2ab60 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
2ab70 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2ab80 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2ab90 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2aba0 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
2abb0 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
2abc0 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
2abd0 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20  rminator at the 
2abe0 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
2abf0 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69  ring.  For clari
2ac00 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65  ty: the value re
2ac10 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75  turned is the nu
2ac20 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
2ac30 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
2ac40 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2ac50 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
2ac60 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75  .** Strings retu
2ac70 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2ac80 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
2ac90 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2aca0 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
2acb0 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
2acc0 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
2acd0 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54  o terminated.  T
2ace0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2acf0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2ad00 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2ad10 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2ad20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74  BLOB is an arbit
2ad30 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c  rary.** pointer,
2ad40 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61   possibly even a
2ad50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2ad60 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2ad70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2ad80 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
2ad90 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  ilar to sqlite3_
2ada0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
2adb0 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65  * but leaves the
2adc0 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31   result in UTF-1
2add0 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  6 in native byte
2ade0 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f   order instead o
2adf0 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20  f UTF-8..** The 
2ae00 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2ae10 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
2ae20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a  in this count..*
2ae30 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20  *.** The object 
2ae40 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2ae50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2ae60 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2ae70 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2ae80 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2ae90 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2aea0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2aeb0 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2aec0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2aed0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2aee0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2aef0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2af00 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2af10 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2af20 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2af30 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2af40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2af50 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2af60 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2af70 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2af80 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2af90 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2afa0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2afb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2afc0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2afd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2afe0 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2aff0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2b000 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2b010 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2b020 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2b030 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2b040 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a  propriate.  For.
2b050 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
2b060 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
2b070 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
2b080 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
2b090 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
2b0a0 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
2b0b0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
2b0c0 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
2b0d0 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
2b0e0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
2b0f0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
2b100 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
2b110 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
2b120 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
2b130 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
2b140 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
2b150 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
2b160 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
2b170 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
2b180 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
2b190 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
2b1a0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
2b1b0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2b1c0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2b1d0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2b1e0 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
2b1f0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
2b200 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
2b210 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
2b220 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2b230 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2b240 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
2b250 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2b260 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2b270 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2b280 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
2b290 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
2b2a0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
2b2b0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2b2c0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
2b2d0 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
2b2e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2b2f0 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
2b300 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2b310 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2b320 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
2b330 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2b340 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2b350 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
2b360 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
2b370 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2b380 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2b390 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
2b3a0 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
2b3b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2b3c0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
2b3d0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
2b3e0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
2b3f0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
2b400 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
2b410 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
2b420 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
2b430 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
2b440 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
2b450 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
2b460 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
2b470 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2b480 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
2b490 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
2b4a0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2b4b0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2b4c0 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
2b4d0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2b4e0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2b4f0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
2b500 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
2b510 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
2b520 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
2b530 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
2b540 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
2b550 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
2b560 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2b570 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2b580 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
2b590 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
2b5a0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
2b5b0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
2b5c0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ote>.**.** The t
2b5d0 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
2b5e0 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
2b5f0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
2b600 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
2b610 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
2b620 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
2b630 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
2b640 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
2b650 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
2b660 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
2b670 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
2b680 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
2b690 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
2b6a0 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
2b6b0 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
2b6c0 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
2b6d0 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
2b6e0 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
2b6f0 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
2b700 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
2b710 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
2b720 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
2b730 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
2b740 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2b750 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2b760 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
2b770 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
2b780 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2b790 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
2b7a0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
2b7b0 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
2b7c0 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
2b7d0 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
2b7e0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
2b7f0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
2b800 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
2b810 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2b820 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2b830 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
2b840 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2b850 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2b860 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2b870 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2b880 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
2b890 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
2b8a0 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
2b8b0 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
2b8c0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2b8d0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2b8e0 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
2b8f0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2b900 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
2b910 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2b920 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2b930 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2b940 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2b950 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2b960 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
2b970 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2b980 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2b990 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
2b9a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2b9b0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
2b9c0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2b9d0 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
2b9e0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2b9f0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2ba00 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2ba10 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
2ba20 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69  >.**.** Conversi
2ba30 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2ba40 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2ba50 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2ba60 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2ba70 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2ba80 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2ba90 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2baa0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2bab0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2bac0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2bad0 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73  r pointer points
2bae0 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65   to will have be
2baf0 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
2bb00 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
2bb10 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
2bb20 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
2bb30 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
2bb40 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
2bb50 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
2bb60 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
2bb70 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
2bb80 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
2bb90 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
2bba0 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
2bbb0 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
2bbc0 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
2bbd0 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
2bbe0 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
2bbf0 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
2bc00 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
2bc10 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
2bc20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2bc30 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2bc40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2bc50 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2bc60 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2bc70 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
2bc80 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2bc90 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2bca0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2bcb0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2bcc0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2bcd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2bce0 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
2bcf0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
2bd00 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
2bd10 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
2bd20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
2bd30 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2bd40 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
2bd50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2bd60 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
2bd70 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
2bd80 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
2bd90 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
2bda0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
2bdb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2bdc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2bdd0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
2bde0 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
2bdf0 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
2be00 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
2be10 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
2be20 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
2be30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2be40 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
2be50 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2be60 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
2be70 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
2be80 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2be90 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
2bea0 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
2beb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2bec0 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ytes()..**.** Th
2bed0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2bee0 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
2bef0 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
2bf00 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
2bf10 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
2bf20 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
2bf30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2bf40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2bf50 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2bf60 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
2bf70 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65   called.  The me
2bf80 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
2bf90 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
2bfa0 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
2bfb0 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
2bfc0 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
2bfd0 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
2bfe0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
2bff0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2c000 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
2c010 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2c020 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
2c030 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2c040 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65  ]..**.** If a me
2c050 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2c060 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2c070 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
2c080 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
2c090 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
2c0a0 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
2c0b0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
2c0c0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
2c0d0 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
2c0e0 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
2c0f0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2c100 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
2c110 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
2c120 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
2c130 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
2c140 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
2c150 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
2c160 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _NOMEM]..**.** I
2c170 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2c180 20 7b 48 31 33 38 30 33 7d 20 54 68 65 20 5b 73   {H13803} The [s
2c190 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2c1a0 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  ob(S,N)] interfa
2c1b0 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2c1c0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
2c1d0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
2c1e0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2c1f0 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
2c200 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2c210 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c220 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 42 4c  ent] S into a BL
2c230 4f 42 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  OB and then retu
2c240 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  rns a.**        
2c250 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65    pointer to the
2c260 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65   converted value
2c270 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 36 7d  ..**.** {H13806}
2c280 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2c290 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d  lumn_bytes(S,N)]
2c2a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c2b0 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
2c2c0 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
2c2d0 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f  es in the BLOB o
2c2e0 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  r string (exclus
2c2f0 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
2c300 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
2c310 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
2c320 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
2c330 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2c340 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
2c350 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2c360 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c370 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20  lob(S,N)] or.** 
2c380 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2c390 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c  3_column_text(S,
2c3a0 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  N)]..**.** {H138
2c3b0 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
2c3c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c3d0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2c3e0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
2c3f0 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
2c400 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  f bytes in the s
2c410 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
2c420 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2c430 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
2c440 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
2c450 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
2c460 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
2c470 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
2c480 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2c490 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c4a0 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16(S,N)]..**.** 
2c4b0 7b 48 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71  {H13812} The [sq
2c4c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
2c4d0 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ble(S,N)] interf
2c4e0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2c4f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
2c500 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
2c510 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2c520 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
2c530 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c540 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c550 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66  ment] S into a f
2c560 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2c570 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  lue and.**      
2c580 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
2c590 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65  py of that value
2c5a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 35 7d  ..**.** {H13815}
2c5b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2c5c0 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69  lumn_int(S,N)] i
2c5d0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2c5e0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c5f0 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
2c600 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
2c610 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2c620 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
2c630 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2c640 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
2c650 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65  o a 64-bit signe
2c660 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a  d integer and.**
2c670 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2c680 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62  s the lower 32 b
2c690 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65  its of that inte
2c6a0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  ger..**.** {H138
2c6b0 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  18} The [sqlite3
2c6c0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c  _column_int64(S,
2c6d0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
2c6e0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2c6f0 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2c700 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2c710 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2c720 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
2c730 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2c740 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c750 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  S into a 64-bit 
2c760 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
2c770 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
2c780 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2c790 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
2c7a0 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20 54 68  *.** {H13821} Th
2c7b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2c7c0 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74  n_text(S,N)] int
2c7d0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2c7e0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c7f0 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
2c800 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
2c810 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2c820 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2c830 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2c840 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
2c850 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2c860 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20  d UTF-8.**      
2c870 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
2c880 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2c890 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
2c8a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34 7d 20  .**.** {H13824} 
2c8b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
2c8c0 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d  umn_text16(S,N)]
2c8d0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2c8e0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2c8f0 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69      Nth column i
2c900 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f  n the current ro
2c910 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2c920 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  set for the.**  
2c930 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2c940 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2c950 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  nto a zero-termi
2c960 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20  nated 2-byte.** 
2c970 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64           aligned
2c980 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
2c990 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67  yte order string
2c9a0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2c9b0 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74           a point
2c9c0 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e  er to that strin
2c9d0 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 37  g..**.** {H13827
2c9e0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2c9f0 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d  olumn_type(S,N)]
2ca00 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ca10 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ns.**          o
2ca20 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55  ne of [SQLITE_NU
2ca30 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54  LL], [SQLITE_INT
2ca40 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
2ca50 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  LOAT],.**       
2ca60 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d     [SQLITE_TEXT]
2ca70 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  , or [SQLITE_BLO
2ca80 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
2ca90 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
2caa0 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e    the Nth column
2cab0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2cac0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2cad0 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
2cae0 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
2caf0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2cb00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33 30 7d  ..**.** {H13830}
2cb10 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2cb20 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d  lumn_value(S,N)]
2cb30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2cb40 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
2cb50 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
2cb60 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2cb70 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2cb80 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
2cb90 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
2cba0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2cbb0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2cbc0 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
2cbd0 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
2cbe0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2cbf0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
2cc00 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2cc10 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2cc20 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2cc30 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2cc40 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
2cc50 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2cc60 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2cc70 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
2cc80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2cc90 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
2cca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
2ccb0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2ccc0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2ccd0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2cce0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2ccf0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
2cd00 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2cd10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
2cd20 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2cd30 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
2cd40 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
2cd50 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2cd60 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2cd70 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
2cd80 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2cd90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2cda0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2cdb0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2cdc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2cdd0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2cde0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
2cdf0 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
2ce00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2ce10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2ce20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
2ce30 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
2ce40 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
2ce50 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
2ce60 7b 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30 30  {H13300} <S70300
2ce70 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S30100>.**.** 
2ce80 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
2ce90 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
2cea0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
2ceb0 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
2cec0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
2ced0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2cee0 77 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63  was executed suc
2cef0 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74  cessfully or not
2cf00 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c   executed at all
2cf10 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45  , then.** SQLITE
2cf20 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
2cf30 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66   If execution of
2cf40 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
2cf50 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a  ailed then an.**
2cf60 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
2cf70 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2cf80 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
2cf90 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ed..**.** This r
2cfa0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
2cfb0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
2cfc0 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65  t during the exe
2cfd0 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  cution of the.**
2cfe0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cff0 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76  ment].  If the v
2d000 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68  irtual machine h
2d010 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65  as not.** comple
2d020 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68  ted execution wh
2d030 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
2d040 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20  is called, that 
2d050 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75  is like.** encou
2d060 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72  ntering an error
2d070 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   or an [sqlite3_
2d080 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65  interrupt | inte
2d090 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d  rrupt]..** Incom
2d0a0 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61  plete updates ma
2d0b0 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  y be rolled back
2d0c0 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e   and transaction
2d0d0 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64  s canceled,.** d
2d0e0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
2d0f0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61  circumstances, a
2d100 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72  nd the.** [error
2d110 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20   code] returned 
2d120 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  will be [SQLITE_
2d130 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ABORT]..**.** IN
2d140 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2d150 7b 48 31 31 33 30 32 7d 20 54 68 65 20 5b 73 71  {H11302} The [sq
2d160 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2d170 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73  )] interface des
2d180 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20 20  troys the.**    
2d190 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2d1a0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64  statement] S and
2d1b0 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a   releases all.**
2d1c0 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79            memory
2d1d0 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75 72   and file resour
2d1e0 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 61 74  ces held by that
2d1f0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b   object..**.** {
2d200 48 31 31 33 30 34 7d 20 49 66 20 74 68 65 20 6d  H11304} If the m
2d210 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2d220 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2d230 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2d240 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2d250 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2d260 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72 6f  returned an erro
2d270 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  r,.**          t
2d280 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  hen [sqlite3_fin
2d290 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72 6e  alize(S)] return
2d2a0 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 72 6f  s that same erro
2d2b0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
2d2c0 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
2d2d0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2d2e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d2f0 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
2d300 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2d310 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53 37  ect {H13330} <S7
2d320 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0300>.**.** The 
2d330 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
2d340 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
2d350 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
2d360 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d370 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
2d380 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2d390 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
2d3a0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
2d3b0 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74  .** Any SQL stat
2d3c0 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
2d3d0 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
2d3e0 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
2d3f0 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
2d400 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2d410 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2d420 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
2d430 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
2d440 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
2d450 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
2d460 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
2d470 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  gs..**.** {H1133
2d480 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2d490 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2d4a0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
2d4b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d4c0 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20  nt] S.**        
2d4d0 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65    back to the be
2d4e0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
2d4f0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rogram..**.** {H
2d500 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f  11334} If the mo
2d510 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2d520 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2d530 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  S)] for the.**  
2d540 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2d550 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
2d560 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2d570 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
2d580 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  DONE],.**       
2d590 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65     or if [sqlite
2d5a0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
2d5b0 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
2d5c0 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
2d5d0 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b            then [
2d5e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2d5f0 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
2d600 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  E_OK]..**.** {H1
2d610 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f 73  1336} If the mos
2d620 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2d630 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2d640 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  )] for the.**   
2d650 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
2d660 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2d670 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
2d680 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
2d690 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65     [sqlite3_rese
2d6a0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
2d6b0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2d6c0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2d6d0 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b 73   {H11338} The [s
2d6e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2d6f0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
2d700 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
2d710 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  alues.**        
2d720 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65    of any [sqlite
2d730 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
2d740 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
2d750 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d760 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ] S..*/.int sqli
2d770 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
2d780 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2d790 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d7a0 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
2d7b0 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
2d7c0 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 30 32  s {H16100} <S202
2d7d0 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
2d7e0 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   {function creat
2d7f0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a  ion routines}.**
2d800 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2d810 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2d820 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a  SQL function}.**
2d830 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c   KEYWORDS: {appl
2d840 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2d850 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  SQL functions}.*
2d860 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20 66  *.** These two f
2d870 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
2d880 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
2d890 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
2d8a0 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
2d8b0 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
2d8c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
2d8d0 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
2d8e0 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
2d8f0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
2d900 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
2d910 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
2d920 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
2d930 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65  ifference betwee
2d940 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20  n the.** two is 
2d950 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
2d960 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e  parameter, the n
2d970 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c  ame of the (scal
2d980 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  ar) function or.
2d990 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69 73  ** aggregate, is
2d9a0 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
2d9b0 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  8 for sqlite3_cr
2d9c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2d9d0 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f  and UTF-16.** fo
2d9e0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2d9f0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a  _function16()..*
2da00 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
2da10 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2da20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2da30 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
2da40 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
2da50 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
2da60 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65 20  d.  If a single 
2da70 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72  program uses mor
2da80 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
2da90 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2daa0 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68  n internally, th
2dab0 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  en SQL functions
2dac0 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69   must be added i
2dad0 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a  ndividually to.*
2dae0 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  * each database 
2daf0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  connection..**.*
2db00 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
2db10 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2db20 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
2db30 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
2db40 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
2db50 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67 74  ined.  The lengt
2db60 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
2db70 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
2db80 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65  bytes, exclusive
2db90 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d   of.** the zero-
2dba0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74  terminator.  Not
2dbb0 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20  e that the name 
2dbc0 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
2dbd0 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a  in bytes, not.**
2dbe0 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e   characters.  An
2dbf0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
2dc00 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
2dc10 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
2dc20 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
2dc30 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   in [SQLITE_ERRO
2dc40 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  R] being returne
2dc50 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  d..**.** The thi
2dc60 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
2dc70 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
2dc80 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2dc90 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
2dca0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2dcb0 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 49  gregate takes. I
2dcc0 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
2dcd0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2dce0 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
2dcf0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2dd00 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
2dd10 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2dd20 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
2dd30 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2dd40 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
2dd50 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
2dd60 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
2dd70 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
2dd80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
2dd90 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
2dda0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e   parameters.  An
2ddb0 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
2ddc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
2ddd0 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20  ould be able to 
2dde0 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74  work.** work wit
2ddf0 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c  h UTF-8, UTF-16l
2de00 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20  e, or UTF-16be. 
2de10 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d   But some implem
2de20 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65  entations may be
2de30 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65  .** more efficie
2de40 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f  nt with one enco
2de50 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65  ding than anothe
2de60 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f 77 65  r.  It is allowe
2de70 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
2de80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2de90 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  nction() or sqli
2dea0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2deb0 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65  ion16() multiple
2dec0 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74  .** times with t
2ded0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2dee0 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
2def0 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54  ent values of eT
2df00 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e 20  extRep..** When 
2df10 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2df20 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2df30 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
2df40 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
2df50 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
2df60 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
2df70 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
2df80 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
2df90 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49  conversion..** I
2dfa0 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
2dfb0 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65  a single impleme
2dfc0 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f  ntation which do
2dfd0 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74  es not care what
2dfe0 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e   text.** encodin
2dff0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  g is used, then 
2e000 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
2e010 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53  ent should be [S
2e020 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
2e030 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72 61  * The fifth para
2e040 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
2e050 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
2e060 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
2e070 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
2e080 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
2e090 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
2e0a0 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
2e0b0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
2e0c0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76  ]..**.** The sev
2e0d0 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64  enth, eighth and
2e0e0 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
2e0f0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
2e100 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
2e110 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
2e120 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
2e130 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
2e140 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2e150 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2e160 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53 51  ate. A scalar SQ
2e170 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2e180 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2e190 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
2e1a0 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
2e1b0 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly, NULL pointe
2e1c0 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  rs should be pas
2e1d0 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
2e1e0 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
2e1f0 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61 67  arameters. An ag
2e200 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2e210 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2e220 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e230 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
2e240 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
2e250 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64  should be passed
2e260 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20 64   for xFunc. To d
2e270 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
2e280 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
2e290 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
2e2a0 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c  pass NULL for al
2e2b0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
2e2c0 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
2e2d0 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74 65  * It is permitte
2e2e0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
2e2f0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2e300 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2e310 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
2e320 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
2e330 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
2e340 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
2e350 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
2e360 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
2e370 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
2e380 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51 4c   encodings.  SQL
2e390 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
2e3a0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2e3b0 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  on most closely 
2e3c0 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
2e3d0 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
2e3e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
2e3f0 75 73 65 64 2e 20 20 41 20 66 75 6e 63 74 69 6f  used.  A functio
2e400 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2e410 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
2e420 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
2e430 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
2e440 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
2e450 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2e460 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
2e470 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
2e480 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65    A function whe
2e490 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
2e4a0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
2e4b0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
2e4c0 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
2e4d0 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
2e4e0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
2e4f0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
2e500 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
2e510 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66 75 6e  rent.  .** A fun
2e520 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2e530 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
2e540 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
2e550 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
2e560 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
2e570 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
2e580 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2e590 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2e5a0 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
2e5b0 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
2e5c0 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74 2d  16..**.** Built-
2e5d0 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
2e5e0 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
2e5f0 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
2e600 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2e610 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ons..** The firs
2e620 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  t application-de
2e630 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77  fined function w
2e640 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65  ith a given name
2e650 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a   overrides all.*
2e660 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74  * built-in funct
2e670 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65  ions in the same
2e680 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2e690 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20  ction] with the 
2e6a0 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53 75  same name..** Su
2e6b0 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61  bsequent applica
2e6c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2e6d0 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ctions of the sa
2e6e0 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65  me name only ove
2e6f0 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20  rride .** prior 
2e700 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e710 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ned functions th
2e720 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 74 20  at are an exact 
2e730 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a  match for the.**
2e740 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d   number of param
2e750 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 65 72  eters and prefer
2e760 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  red encoding..**
2e770 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61 74 69  .** An applicati
2e780 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2e790 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
2e7a0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
2e7b0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
2e7c0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
2e7d0 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
2e7e0 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
2e7f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e800 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
2e810 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
2e820 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2e830 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
2e840 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2e850 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ning..**.** INVA
2e860 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
2e870 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69  16103} The [sqli
2e880 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e890 69 6f 6e 31 36 28 44 2c 58 2c 2e 2e 2e 29 5d 20  ion16(D,X,...)] 
2e8a0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2e8b0 62 65 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20  behave.**       
2e8c0 20 20 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63     as [sqlite3_c
2e8d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2e8e0 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 20 65 76 65 72  ,X,...)] in ever
2e8f0 79 20 77 61 79 20 65 78 63 65 70 74 20 74 68 61  y way except tha
2e900 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  t it.**         
2e910 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2e920 58 20 61 72 67 75 6d 65 6e 74 20 61 73 20 7a 65  X argument as ze
2e930 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2e940 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20  F-16.**         
2e950 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2e960 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 73  er instead of as
2e970 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2e980 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
2e990 31 36 31 30 36 7d 20 41 20 73 75 63 63 65 73 73  16106} A success
2e9a0 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
2e9b0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2e9c0 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74    [sqlite3_creat
2e9d0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2e9e0 2c 45 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ,E,...)] interfa
2e9f0 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74 65  ce shall registe
2ea00 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  r.**          or
2ea10 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61   replaces callba
2ea20 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20  ck functions in 
2ea30 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2ea40 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20  nnection] D.**  
2ea50 20 20 20 20 20 20 20 20 75 73 65 64 20 74 6f 20          used to 
2ea60 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2ea70 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64  L function named
2ea80 20 58 20 77 69 74 68 20 4e 20 70 61 72 61 6d 65   X with N parame
2ea90 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
2eaa0 20 61 6e 64 20 68 61 76 69 6e 67 20 61 20 70 72   and having a pr
2eab0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2eac0 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a  oding of E..**.*
2ead0 2a 20 7b 48 31 36 31 30 39 7d 20 41 20 73 75 63  * {H16109} A suc
2eae0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2eaf0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2eb00 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2eb10 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20  ,P,F,S,L)].**   
2eb20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 70         shall rep
2eb30 6c 61 63 65 20 74 68 65 20 50 2c 20 46 2c 20 53  lace the P, F, S
2eb40 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66  , and L values f
2eb50 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61  rom any prior ca
2eb60 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  lls with.**     
2eb70 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c       the same D,
2eb80 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c   X, N, and E val
2eb90 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  ues..**.** {H161
2eba0 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
2ebb0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2ebc0 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  (D,X,...)] inter
2ebd0 66 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c 0a  face shall fail.
2ebe0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74  **          if t
2ebf0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2ec00 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20  name X is.**    
2ec10 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61        longer tha
2ec20 6e 20 32 35 35 20 62 79 74 65 73 20 65 78 63 6c  n 255 bytes excl
2ec30 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
2ec40 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
2ec50 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20 54 68 65  .** {H16118} The
2ec60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ec70 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2ec80 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 69 6e 74 65  E,P,F,S,L)] inte
2ec90 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  rface.**        
2eca0 20 20 73 68 61 6c 6c 20 66 61 69 6c 20 75 6e 6c    shall fail unl
2ecb0 65 73 73 20 65 69 74 68 65 72 20 46 20 69 73 20  ess either F is 
2ecc0 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c  NULL and S and L
2ecd0 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72   are non-NULL or
2ece0 0a 2a 2a 2a 20 20 20 20 20 20 20 20 20 46 20 69  .***         F i
2ecf0 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53  s non-NULL and S
2ed00 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2e   and L are NULL.
2ed10 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 31 7d 20  .**.** {H16121} 
2ed20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2ed30 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e  ate_function(D,.
2ed40 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  ..)] interface s
2ed50 68 61 6c 6c 20 66 61 69 6c 73 20 77 69 74 68 20  hall fails with 
2ed60 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  an.**          e
2ed70 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
2ed80 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74 68  LITE_BUSY] if th
2ed90 65 72 65 20 65 78 69 73 74 20 5b 70 72 65 70 61  ere exist [prepa
2eda0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a  red statements].
2edb0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 6f  **          asso
2edc0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2edd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ede0 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
2edf0 48 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71 6c  H16124} The [sql
2ee00 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ee10 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
2ee20 20 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c   interface shall
2ee30 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a 20 20 20   fail with.**   
2ee40 20 20 20 20 20 20 20 61 6e 20 65 72 72 6f 72 20         an error 
2ee50 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
2ee60 45 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d 65  ERROR] if parame
2ee70 74 65 72 20 4e 20 69 73 20 6c 65 73 73 0a 2a 2a  ter N is less.**
2ee80 20 20 20 20 20 20 20 20 20 20 74 68 61 6e 20 2d            than -
2ee90 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
2eea0 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  n 127..**.** {H1
2eeb0 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69 73 20  6127} When N is 
2eec0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
2eed0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2eee0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2eef0 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2ef00 20 20 20 69 6e 74 65 72 66 61 63 65 20 73 68 61     interface sha
2ef10 6c 6c 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  ll register call
2ef20 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f  backs to be invo
2ef30 6b 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  ked for the.**  
2ef40 20 20 20 20 20 20 20 20 53 51 4c 20 66 75 6e 63          SQL func
2ef50 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
2ef60 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 74 68   named X when th
2ef70 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
2ef80 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c  ments to the SQL
2ef90 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
2efa0 20 20 20 20 20 20 20 20 20 65 78 61 63 74 6c 79           exactly
2efb0 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33   N..**.** {H1613
2efc0 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c  0} When N is -1,
2efd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2efe0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2eff0 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  X,N,...)].**    
2f000 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20        interface 
2f010 73 68 61 6c 6c 20 72 65 67 69 73 74 65 72 20 63  shall register c
2f020 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69  allbacks to be i
2f030 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53  nvoked for the S
2f040 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  QL.**          f
2f050 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20  unction named X 
2f060 77 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20  with any number 
2f070 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  of arguments..**
2f080 0a 2a 2a 20 7b 48 31 36 31 33 33 7d 20 57 68 65  .** {H16133} Whe
2f090 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
2f0a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f0b0 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a  ion(D,X,N,...)].
2f0c0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63  **          spec
2f0d0 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ify multiple imp
2f0e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2f0f0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2f100 6e 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  n X.**          
2f110 61 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70  and when one imp
2f120 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20  lementation has 
2f130 4e 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68  N>=0 and the oth
2f140 65 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a  er has N=(-1).**
2f150 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6d            the im
2f160 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2f170 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 73  h a non-zero N s
2f180 68 61 6c 6c 20 62 65 20 70 72 65 66 65 72 72 65  hall be preferre
2f190 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 36  d..**.** {H16136
2f1a0 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  } When calls to 
2f1b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f1c0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2f1d0 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2f1e0 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69     specify multi
2f1f0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2f200 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2f210 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 0a  function X with.
2f220 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2f230 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 61  same number of a
2f240 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 20 77  rguments N but w
2f250 69 74 68 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a  ith different.**
2f260 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 69            encodi
2f270 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 68 65 20  ngs E, then the 
2f280 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2f290 68 65 72 65 20 45 20 6d 61 74 63 68 65 73 20 74  here E matches t
2f2a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  he.**          d
2f2b0 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
2f2c0 20 73 68 61 6c 6c 20 70 72 65 66 65 72 72 65 64   shall preferred
2f2d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 39 7d  ..**.** {H16139}
2f2e0 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61 74   For an aggregat
2f2f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  e SQL function c
2f300 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
2f310 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2f320 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f330 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c  n(D,X,N,E,P,0,S,
2f340 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c 69 7a 65  L)] the finalize
2f350 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  r.**          fu
2f360 6e 63 74 69 6f 6e 20 4c 20 73 68 61 6c 6c 20 61  nction L shall a
2f370 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65 64  lways be invoked
2f380 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 66   exactly once if
2f390 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2f3a0 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 53   step function S
2f3b0 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   is called one o
2f3c0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
2f3d0 0a 2a 2a 20 7b 48 31 36 31 34 32 7d 20 57 68 65  .** {H16142} Whe
2f3e0 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
2f3f0 20 65 69 74 68 65 72 20 74 68 65 20 78 46 75 6e   either the xFun
2f400 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63 74  c or xStep funct
2f410 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ion of.**       
2f420 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f     an applicatio
2f430 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2f440 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2f450 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 20  ate created.**  
2f460 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69          by [sqli
2f470 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f480 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ion()] or [sqlit
2f490 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f4a0 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  on16()],.**     
2f4b0 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 61 72       then the ar
2f4c0 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ray of [sqlite3_
2f4d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20 70  value] objects p
2f4e0 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20  assed as the.** 
2f4f0 20 20 20 20 20 20 20 20 20 74 68 69 72 64 20 70           third p
2f500 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20 62  arameter shall b
2f510 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
2f520 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2f530 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  cts..*/.int sqli
2f540 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f550 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
2f560 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
2f570 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2f580 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2f590 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2f5a0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2f5b0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2f5c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2f5d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2f5e0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2f5f0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2f600 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2f610 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2f620 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2f630 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69  3_context*).);.i
2f640 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2f650 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
2f660 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2f670 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
2f680 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2f690 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2f6a0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2f6b0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2f6c0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2f6d0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2f6e0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2f6f0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2f700 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2f710 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2f720 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2f730 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2f740 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  xt*).);../*.** C
2f750 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
2f760 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 37 7d  codings {H10267}
2f770 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 31 30   <S50200> <H1610
2f780 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  0>.**.** These c
2f790 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
2f7a0 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
2f7b0 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
2f7c0 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
2f7d0 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
2f7e0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
2f7f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2f800 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
2f810 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2f820 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
2f830 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2f840 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
2f850 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
2f860 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
2f870 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
2f880 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
2f890 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f8a0 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
2f8b0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2f8c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f  reate_function o
2f8d0 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
2f8e0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
2f8f0 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
2f900 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2f910 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
2f920 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2f930 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
2f940 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
2f950 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
2f960 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
2f970 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
2f980 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
2f990 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
2f9a0 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
2f9b0 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
2f9c0 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
2f9d0 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
2f9e0 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
2f9f0 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
2fa00 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
2fa10 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
2fa20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
2fa30 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72    To help encour
2fa40 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76  age people to av
2fa50 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  oid.** using the
2fa60 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65  se functions, we
2fa70 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74   are not going t
2fa80 6f 20 74 65 6c 6c 20 79 6f 75 20 77 61 6e 74 20  o tell you want 
2fa90 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e  they do..*/.#ifn
2faa0 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
2fab0 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54  DEPRECATED.SQLIT
2fac0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2fad0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2fae0 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
2faf0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
2fb00 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2fb10 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
2fb20 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
2fb30 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
2fb40 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2fb50 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
2fb60 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2fb70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
2fb80 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2fb90 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
2fba0 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
2fbb0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
2fbc0 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
2fbd0 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
2fbe0 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
2fbf0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2fc00 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
2fc10 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
2fc20 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
2fc30 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69  ,int),void*,sqli
2fc40 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
2fc50 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
2fc60 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
2fc70 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d  L Function Param
2fc80 65 74 65 72 20 56 61 6c 75 65 73 20 7b 48 31 35  eter Values {H15
2fc90 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  100} <S20200>.**
2fca0 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
2fcb0 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
2fcc0 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
2fcd0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
2fce0 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
2fcf0 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
2fd00 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
2fd10 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
2fd20 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
2fd30 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
2fd40 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
2fd50 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
2fd60 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
2fd70 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
2fd80 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
2fd90 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
2fda0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2fdb0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
2fdc0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2fdd0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
2fde0 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
2fdf0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
2fe00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
2fe10 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
2fe20 20 54 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   The 4th paramet
2fe30 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
2fe40 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
2fe50 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
2fe60 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
2fe70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2fe80 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
2fe90 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
2fea0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
2feb0 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
2fec0 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
2fed0 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
2fee0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
2fef0 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
2ff00 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
2ff10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2ff20 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
2ff30 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
2ff40 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
2ff50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2ff60 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
2ff70 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
2ff80 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
2ff90 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
2ffa0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2ffb0 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
2ffc0 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
2ffd0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
2ffe0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2fff0 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
30000 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
30010 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
30020 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
30030 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
30040 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
30050 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
30060 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30070 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
30080 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
30090 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
300a0 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
300b0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
300c0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
300d0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
300e0 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72  e_text16() inter
300f0 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20  face extracts a 
30100 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
30110 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
30120 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65  yte-order of the
30130 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20   host machine.  
30140 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
30150 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
30160 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
30170 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
30180 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
30190 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
301a0 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
301b0 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
301c0 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
301d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
301e0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
301f0 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
30200 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
30210 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
30220 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
30230 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
30240 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
30250 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
30260 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
30270 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
30280 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
30290 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
302a0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
302b0 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
302c0 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
302d0 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
302e0 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
302f0 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
30300 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
30310 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
30320 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
30330 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
30340 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
30350 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
30360 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
30370 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
30380 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
30390 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
303a0 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
303b0 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
303c0 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
303d0 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
303e0 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
303f0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
30400 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
30410 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30420 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
30430 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
30440 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
30450 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
30460 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
30470 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
30480 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
30490 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
304a0 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
304b0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
304c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
304d0 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
304e0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
304f0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
30500 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
30510 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
30520 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
30530 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
30540 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
30550 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a   parameters..**.
30560 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
30570 2a 0a 2a 2a 20 7b 48 31 35 31 30 33 7d 20 54 68  *.** {H15103} Th
30580 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
30590 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74 65 72 66  _blob(V)] interf
305a0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
305b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
305c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
305d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
305e0 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64 20  into a BLOB and 
305f0 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
30600 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
30610 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65 72  er to the conver
30620 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  ted value..**.**
30630 20 7b 48 31 35 31 30 36 7d 20 54 68 65 20 5b 73   {H15106} The [s
30640 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
30650 65 73 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  es(V)] interface
30660 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
30670 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
30680 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
30690 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28  BLOB or string (
306a0 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
306b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
306c0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20  o terminator on 
306d0 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74  the string) that
306e0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79   was returned by
306f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30700 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
30710 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61  l to [sqlite3_va
30720 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 6f 72 0a  lue_blob(V)] or.
30730 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
30740 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
30750 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  V)]..**.** {H151
30760 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  09} The [sqlite3
30770 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 56  _value_bytes16(V
30780 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
30790 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  urns the.**     
307a0 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62       number of b
307b0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
307c0 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
307d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
307e0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
307f0 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
30800 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
30810 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
30820 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
30830 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
30840 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 56  3_value_text16(V
30850 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
30860 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30870 65 78 74 31 36 62 65 28 56 29 5d 2c 20 6f 72 20  ext16be(V)], or 
30880 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30890 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a 2a 2a 0a  ext16le(V)]..**.
308a0 2a 2a 20 7b 48 31 35 31 31 32 7d 20 54 68 65 20  ** {H15112} The 
308b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
308c0 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74 65 72 66  ouble(V)] interf
308d0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
308e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
308f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30900 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
30910 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20  into a floating 
30920 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a  point value and.
30930 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
30940 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  rns a copy of th
30950 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  at value..**.** 
30960 7b 48 31 35 31 31 35 7d 20 54 68 65 20 5b 73 71  {H15115} The [sq
30970 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
30980 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
30990 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
309a0 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
309b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
309c0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
309d0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
309e0 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20  nteger and.**   
309f0 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74         returns t
30a00 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73  he lower 32 bits
30a10 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
30a20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 38 7d  ..**.** {H15118}
30a30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
30a40 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d 20 69 6e  lue_int64(V)] in
30a50 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
30a60 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30a70 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
30a80 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30a90 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  t V into a 64-bi
30aa0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
30ab0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
30ac0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
30ad0 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
30ae0 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 31 7d 20  .**.** {H15121} 
30af0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
30b00 75 65 5f 74 65 78 74 28 56 29 5d 20 69 6e 74 65  ue_text(V)] inte
30b10 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
30b20 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
30b30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30b40 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
30b50 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  V into a zero-te
30b60 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
30b70 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
30b80 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  g and returns a 
30b90 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
30ba0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
30bb0 31 35 31 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  15124} The [sqli
30bc0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
30bd0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
30be0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
30bf0 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
30c00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30c10 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
30c20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
30c30 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
30c40 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
30c50 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
30c60 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  order.**        
30c70 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74    string and ret
30c80 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
30c90 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
30ca0 2a 0a 2a 2a 20 7b 48 31 35 31 32 37 7d 20 54 68  *.** {H15127} Th
30cb0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
30cc0 5f 74 65 78 74 31 36 62 65 28 56 29 5d 20 69 6e  _text16be(V)] in
30cd0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
30ce0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30cf0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
30d00 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30d10 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  t V into a zero-
30d20 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74  terminated 2-byt
30d30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  e.**          al
30d40 69 67 6e 65 64 20 55 54 46 2d 31 36 20 62 69 67  igned UTF-16 big
30d50 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
30d60 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72      string and r
30d70 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
30d80 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e   to that string.
30d90 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 30 7d 20  .**.** {H15130} 
30da0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
30db0 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 20  ue_text16le(V)] 
30dc0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
30dd0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
30de0 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
30df0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
30e00 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72  ect V into a zer
30e10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62  o-terminated 2-b
30e20 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  yte.**          
30e30 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6c  aligned UTF-16 l
30e40 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20  ittle-endian.** 
30e50 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
30e60 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
30e70 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
30e80 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
30e90 31 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  133} The [sqlite
30ea0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 56 29 5d  3_value_type(V)]
30eb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30ec0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ns.**          o
30ed0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55  ne of [SQLITE_NU
30ee0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54  LL], [SQLITE_INT
30ef0 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
30f00 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  LOAT],.**       
30f10 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d     [SQLITE_TEXT]
30f20 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  , or [SQLITE_BLO
30f30 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
30f40 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  e for.**        
30f50 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    the [sqlite3_v
30f60 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 2e 0a  alue] object V..
30f70 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 36 7d 20 54  **.** {H15136} T
30f80 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30f90 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 56  e_numeric_type(V
30fa0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
30fb0 76 65 72 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  verts.**        
30fc0 20 20 74 68 65 20 5b 70 72 6f 74 65 63 74 65 64    the [protected
30fd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
30fe0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 65 69  object V into ei
30ff0 74 68 65 72 20 61 6e 20 69 6e 74 65 67 65 72 20  ther an integer 
31000 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  or.**          a
31010 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
31020 76 61 6c 75 65 20 69 66 20 69 74 20 63 61 6e 20  value if it can 
31030 64 6f 20 73 6f 20 77 69 74 68 6f 75 74 20 6c 6f  do so without lo
31040 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ss of.**        
31050 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 61    information, a
31060 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e 65 20 6f  nd returns one o
31070 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c  f [SQLITE_NULL],
31080 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
31090 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b  LITE_INTEGER], [
310a0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
310b0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72  SQLITE_TEXT], or
310c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
310d0 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70  LITE_BLOB] as ap
310e0 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68  propriate for th
310f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
31100 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
31110 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
31120 20 61 66 74 65 72 20 74 68 65 20 63 6f 6e 76 65   after the conve
31130 72 73 69 6f 6e 20 61 74 74 65 6d 70 74 2e 0a 2a  rsion attempt..*
31140 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
31150 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
31160 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31170 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
31180 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
31190 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
311a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
311b0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
311c0 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  ue*);.double sql
311d0 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
311e0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
311f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
31200 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33  alue_int(sqlite3
31210 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65  _value*);.sqlite
31220 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
31230 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69  value_int64(sqli
31240 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
31250 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
31260 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
31270 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  text(sqlite3_val
31280 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
31290 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
312a0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
312b0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
312c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
312d0 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
312e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
312f0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31300 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
31310 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31320 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
31330 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  e_type(sqlite3_v
31340 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
31350 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
31360 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
31370 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
31380 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
31390 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
313a0 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36 32  on Context {H162
313b0 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  10} <S20200>.**.
313c0 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** The implement
313d0 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67 61  ation of aggrega
313e0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
313f0 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e   use this routin
31400 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a 2a  e to allocate.**
31410 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f 72   a structure for
31420 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
31430 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tate..**.** The 
31440 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
31450 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31460 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74 69  _context() routi
31470 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  ne is called for
31480 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72   a.** particular
31490 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c 69   aggregate, SQLi
314a0 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42 79  te allocates nBy
314b0 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  tes of memory, z
314c0 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a 2a  eroes out that.*
314d0 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  * memory, and re
314e0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
314f0 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e 64  to it. On second
31500 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
31510 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
31520 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
31530 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
31540 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
31550 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a 2a  unction index,.*
31560 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
31570 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 54  r is returned. T
31580 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
31590 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  n of the aggrega
315a0 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74 68  te can use.** th
315b0 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66 65  e returned buffe
315c0 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65 20  r to accumulate 
315d0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  data..**.** SQLi
315e0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
315f0 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f 63   frees the alloc
31600 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65 6e  ated buffer when
31610 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
31620 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  * query conclude
31630 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
31640 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  st parameter sho
31650 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f 66  uld be a copy of
31660 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
31670 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
31680 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
31690 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
316a0 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
316b0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
316c0 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
316d0 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
316e0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e 0a  egate function..
316f0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
31700 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
31710 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
31720 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
31730 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
31740 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
31750 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
31760 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
31770 2a 20 7b 48 31 36 32 31 31 7d 20 54 68 65 20 66  * {H16211} The f
31780 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  irst invocation 
31790 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  of [sqlite3_aggr
317a0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
317b0 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20  N)] for.**      
317c0 20 20 20 20 61 20 70 61 72 74 69 63 75 6c 61 72      a particular
317d0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 61 6e 20   instance of an 
317e0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
317f0 6f 6e 20 28 66 6f 72 20 61 20 70 61 72 74 69 63  on (for a partic
31800 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ular.**         
31810 20 63 6f 6e 74 65 78 74 20 43 29 20 63 61 75 73   context C) caus
31820 65 73 20 53 51 4c 69 74 65 20 74 6f 20 61 6c 6c  es SQLite to all
31830 6f 63 61 74 65 20 4e 20 62 79 74 65 73 20 6f 66  ocate N bytes of
31840 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20 20 20 20   memory,.**     
31850 20 20 20 20 20 7a 65 72 6f 20 74 68 61 74 20 6d       zero that m
31860 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
31870 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  n a pointer to t
31880 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 6d 65 6d  he allocated mem
31890 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  ory..**.** {H162
318a0 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f 72 79 20  13} If a memory 
318b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
318c0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 0a 2a   occurs during.*
318d0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
318e0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
318f0 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74 68 65 6e  ntext(C,N)] then
31900 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   the function re
31910 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a 2a 20 7b  turns 0..**.** {
31920 48 31 36 32 31 35 7d 20 53 65 63 6f 6e 64 20 61  H16215} Second a
31930 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  nd subsequent in
31940 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a 2a 2a 20  vocations of.** 
31950 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
31960 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
31970 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 20 74 68  ext(C,N)] for th
31980 65 20 73 61 6d 65 20 63 6f 6e 74 65 78 74 20 70  e same context p
31990 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20 20 20 20  ointer C.**     
319a0 20 20 20 20 20 69 67 6e 6f 72 65 20 74 68 65 20       ignore the 
319b0 4e 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  N parameter and 
319c0 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
319d0 20 74 6f 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   to the same.** 
319e0 20 20 20 20 20 20 20 20 20 62 6c 6f 63 6b 20 6f           block o
319f0 66 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  f memory returne
31a00 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 69  d by the first i
31a10 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
31a20 20 7b 48 31 36 32 31 37 7d 20 54 68 65 20 6d 65   {H16217} The me
31a30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
31a40 79 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  y [sqlite3_aggre
31a50 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
31a60 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
31a70 20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20    automatically 
31a80 66 72 65 65 64 20 6f 6e 20 74 68 65 20 6e 65 78  freed on the nex
31a90 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
31aa0 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 20  e3_reset()].**  
31ab0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
31ac0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
31ad0 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
31ae0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 63 6f 6e  d statement] con
31af0 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20  taining.**      
31b00 20 20 20 20 74 68 65 20 61 67 67 72 65 67 61 74      the aggregat
31b10 65 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63  e function assoc
31b20 69 61 74 65 64 20 77 69 74 68 20 63 6f 6e 74 65  iated with conte
31b30 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  xt C..*/.void *s
31b40 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31b50 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
31b60 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
31b70 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
31b80 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
31b90 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
31ba0 20 7b 48 31 36 32 34 30 7d 20 3c 53 32 30 32 30   {H16240} <S2020
31bb0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
31bc0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
31bd0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
31be0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
31bf0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
31c00 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
31c10 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
31c20 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
31c30 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
31c40 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31c50 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
31c60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31c70 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
31c80 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
31c90 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
31ca0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
31cb0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
31cc0 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ion. {END}.**.**
31cd0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
31ce0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
31cf0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
31d00 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
31d10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31d20 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
31d30 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
31d40 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
31d50 2a 2a 20 7b 48 31 36 32 34 33 7d 20 54 68 65 20  ** {H16243} The 
31d60 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
31d70 74 61 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ta(C)] interface
31d80 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
31d90 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
31da0 20 20 20 50 20 70 6f 69 6e 74 65 72 20 66 72 6f     P pointer fro
31db0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  m the [sqlite3_c
31dc0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
31dd0 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
31de0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
31df0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31e00 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 4e  function16(D,X,N
31e10 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c  ,E,P,F,S,L)] cal
31e20 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  l that.**       
31e30 20 20 20 72 65 67 69 73 74 65 72 65 64 20 74 68     registered th
31e40 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
31e50 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b  ssociated with [
31e60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
31e70 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c   C..*/.void *sql
31e80 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
31e90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
31ea0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31eb0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
31ec0 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
31ed0 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c 53  ions {H16250} <S
31ee0 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a 2a  60600><S20200>.*
31ef0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31f00 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
31f10 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  le() interface r
31f20 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
31f30 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
31f40 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
31f50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68   connection] (th
31f60 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29  e 1st parameter)
31f70 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
31f80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31f90 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
31fa0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31fb0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
31fc0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
31fd0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
31fe0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
31ff0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
32000 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ion..**.** INVAR
32010 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
32020 36 32 35 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  6253} The [sqlit
32030 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
32040 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65 72 66 61  ndle(C)] interfa
32050 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
32060 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  y of the.**     
32070 20 20 20 20 20 44 20 70 6f 69 6e 74 65 72 20 66       D pointer f
32080 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
32090 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
320a0 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
320b0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
320c0 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
320d0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58  e_function16(D,X
320e0 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20 63  ,N,E,P,F,S,L)] c
320f0 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20 20  all that.**     
32100 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
32110 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
32120 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
32130 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
32140 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  t] C..*/.sqlite3
32150 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
32160 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
32170 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
32180 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32190 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
321a0 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 30 7d  ry Data {H16270}
321b0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
321c0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
321d0 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
321e0 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
321f0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
32200 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
32210 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
32220 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
32230 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
32240 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
32250 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
32260 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
32270 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
32280 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
32290 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
322a0 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
322b0 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
322c0 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
322d0 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
322e0 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
322f0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
32300 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
32310 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
32320 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
32330 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
32340 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
32350 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
32360 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
32370 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
32380 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
32390 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
323a0 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
323b0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
323c0 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
323d0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
323e0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
323f0 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
32400 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
32410 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
32420 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
32430 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
32440 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
32450 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
32460 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
32470 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
32480 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  on..**.** The sq
32490 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
324a0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
324b0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
324c0 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
324d0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
324e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
324f0 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
32500 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
32510 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
32520 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
32530 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32540 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65  nction. If no me
32550 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
32560 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74  ever.** been set
32570 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67   for the Nth arg
32580 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
32590 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
325a0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
325b0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
325c0 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64  eter has changed
325d0 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
325e0 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a  data was set,.**
325f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
32600 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75  t_auxdata() retu
32610 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
32620 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
32630 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
32640 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  a() interface sa
32650 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61  ves the metadata
32660 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
32670 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  y its 3rd parame
32680 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64  ter as the metad
32690 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
326a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
326b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
326c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
326d0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a  .  Subsequent.**
326e0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
326f0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
32700 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69  might return thi
32710 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61  s data, if it ha
32720 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65  s.** not been de
32730 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69  stroyed..** If i
32740 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  t is not NULL, S
32750 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
32760 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
32770 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76  .** function giv
32780 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61  en by the 4th pa
32790 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
327a0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
327b0 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64   on.** the metad
327c0 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72  ata when the cor
327d0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
327e0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
327f0 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  anges.** or when
32800 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
32810 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68  nt completes, wh
32820 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
32830 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  rst..**.** SQLit
32840 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c  e is free to cal
32850 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  l the destructor
32860 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61   and drop metada
32870 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72  ta on any.** par
32880 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
32890 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
328a0 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75  me.  The only gu
328b0 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a  arantee is that.
328c0 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ** the destructo
328d0 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
328e0 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
328f0 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e  data is dropped.
32900 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69  .**.** In practi
32910 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
32920 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
32930 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
32940 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
32950 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
32960 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
32970 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
32980 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
32990 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76  values and SQL v
329a0 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  ariables..**.** 
329b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
329c0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
329d0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
329e0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
329f0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
32a00 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
32a10 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
32a20 0a 2a 2a 20 7b 48 31 36 32 37 32 7d 20 54 68 65  .** {H16272} The
32a30 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
32a40 78 64 61 74 61 28 43 2c 4e 29 5d 20 69 6e 74 65  xdata(C,N)] inte
32a50 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
32a60 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
32a70 20 20 20 20 74 6f 20 6d 65 74 61 64 61 74 61 20      to metadata 
32a80 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
32a90 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65  the Nth paramete
32aa0 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  r of the SQL fun
32ab0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
32ac0 20 20 77 68 6f 73 65 20 63 6f 6e 74 65 78 74 20    whose context 
32ad0 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c 20 69 66  is C, or NULL if
32ae0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74   there is no met
32af0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
32b00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
32b10 68 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  h that parameter
32b20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 34 7d  ..**.** {H16274}
32b30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
32b40 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
32b50 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 73  D)] interface as
32b60 73 69 67 6e 73 20 61 20 6d 65 74 61 64 61 74 61  signs a metadata
32b70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
32b80 6e 74 65 72 20 50 20 74 6f 20 74 68 65 20 4e 74  nter P to the Nt
32b90 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  h parameter of t
32ba0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
32bb0 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a  with context C..
32bc0 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 36 7d 20 53  **.** {H16276} S
32bd0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
32be0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
32bf0 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65   D with a single
32c00 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
32c10 20 20 20 20 20 20 77 68 69 63 68 20 69 73 20 74        which is t
32c20 68 65 20 6d 65 74 61 64 61 74 61 20 70 6f 69 6e  he metadata poin
32c30 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69 6e 67 20  ter P following 
32c40 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
32c50 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
32c60 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
32c70 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c 69 74 65  ,D)] when SQLite
32c80 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 0a   ceases to hold.
32c90 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
32ca0 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20  metadata..**.** 
32cb0 7b 48 31 36 32 37 37 7d 20 53 51 4c 69 74 65 20  {H16277} SQLite 
32cc0 63 65 61 73 65 73 20 74 6f 20 68 6f 6c 64 20 6d  ceases to hold m
32cd0 65 74 61 64 61 74 61 20 66 6f 72 20 61 6e 20 53  etadata for an S
32ce0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  QL function para
32cf0 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
32d00 20 20 77 68 65 6e 20 74 68 65 20 76 61 6c 75 65    when the value
32d10 20 6f 66 20 74 68 61 74 20 70 61 72 61 6d 65 74   of that paramet
32d20 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  er changes..**.*
32d30 2a 20 7b 48 31 36 32 37 38 7d 20 57 68 65 6e 20  * {H16278} When 
32d40 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
32d50 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69  data(C,N,P,D)] i
32d60 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 64  s invoked, the d
32d70 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 20 20 20  estructor.**    
32d80 20 20 20 20 20 20 69 73 20 63 61 6c 6c 65 64 20        is called 
32d90 66 6f 72 20 61 6e 79 20 70 72 69 6f 72 20 6d 65  for any prior me
32da0 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
32db0 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  d with the same 
32dc0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
32dd0 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 20 61       context C a
32de0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 4e 2e 0a  nd parameter N..
32df0 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 39 7d 20 53  **.** {H16279} S
32e00 51 4c 69 74 65 20 77 69 6c 6c 20 63 61 6c 6c 20  QLite will call 
32e10 64 65 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20  destructors for 
32e20 61 6e 79 20 6d 65 74 61 64 61 74 61 20 69 74 20  any metadata it 
32e30 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a 20 20 20  is holding.**   
32e40 20 20 20 20 20 20 20 69 6e 20 61 20 70 61 72 74         in a part
32e50 69 63 75 6c 61 72 20 5b 70 72 65 70 61 72 65 64  icular [prepared
32e60 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 77 68   statement] S wh
32e70 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  en either.**    
32e80 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
32e90 65 73 65 74 28 53 29 5d 20 6f 72 20 5b 73 71 6c  eset(S)] or [sql
32ea0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
32eb0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2f 0a  ] is called..*/.
32ec0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
32ed0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
32ee0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
32ef0 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
32f00 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
32f10 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
32f20 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
32f30 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
32f40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32f50 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
32f60 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
32f70 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 20  ructor Behavior 
32f80 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31 30 30  {H10280} <S30100
32f90 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  >.**.** These ar
32fa0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73  e special values
32fb0 20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63   for the destruc
32fc0 74 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73  tor that is pass
32fd0 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20  ed in as the.** 
32fe0 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74  final argument t
32ff0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
33000 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
33010 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74 68 65  blob()].  If the
33020 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
33030 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
33040 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
33050 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
33060 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
33070 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
33080 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
33090 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
330a0 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
330b0 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c  yed.  The.** SQL
330c0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
330d0 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
330e0 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
330f0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
33100 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
33110 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
33120 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
33130 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
33140 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
33150 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
33160 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
33170 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
33180 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
33190 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
331a0 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
331b0 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
331c0 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
331d0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
331e0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
331f0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
33200 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
33210 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
33220 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
33230 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
33240 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
33250 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
33260 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
33270 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
33280 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
33290 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
332a0 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31 36 34  L Function {H164
332b0 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  00} <S20200>.**.
332c0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
332d0 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
332e0 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
332f0 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
33300 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
33310 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
33320 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
33330 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
33340 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
33350 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
33360 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
33370 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
33380 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
33390 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
333a0 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
333b0 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
333c0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
333d0 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
333e0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
333f0 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
33400 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
33410 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
33420 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
33430 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
33440 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
33450 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
33460 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
33470 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  n..**.** The sql
33480 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
33490 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
334a0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
334b0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
334c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
334d0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
334e0 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
334f0 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
33500 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
33510 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
33520 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
33530 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
33540 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
33550 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ameter..**.** Th
33560 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33570 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
33580 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
33590 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
335a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
335b0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
335c0 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
335d0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
335e0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
335f0 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
33600 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
33610 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
33620 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  meter..**.** The
33630 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33640 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
33650 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
33660 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
33670 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33680 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
33690 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
336a0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
336b0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
336c0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
336d0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
336e0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
336f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33700 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
33710 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
33720 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
33730 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
33740 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
33750 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
33760 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
33770 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
33780 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
33790 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
337a0 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
337b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
337c0 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
337d0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
337e0 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20 69 6e  sage.  SQLite in
337f0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
33800 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
33810 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
33820 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
33830 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c 69 74   as UTF-8. SQLit
33840 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
33850 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
33860 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33870 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
33880 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
33890 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49 66 20  byte order.  If 
338a0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
338b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
338c0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
338d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
338e0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
338f0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
33900 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
33910 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
33920 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
33930 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
33940 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
33950 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69 72 64  .** If the third
33960 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
33970 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33980 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
33990 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
339a0 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
339b0 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
339c0 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
339d0 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
339e0 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
339f0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
33a00 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
33a10 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20 73 71  ssage..** The sq
33a20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33a30 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
33a40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33a50 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
33a60 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
33a70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
33a80 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
33a90 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
33aa0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
33ab0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
33ac0 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
33ad0 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
33ae0 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
33af0 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
33b00 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  arm..** The sqli
33b10 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33b20 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
33b30 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
33b40 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
33b50 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
33b60 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
33b70 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
33b80 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ion.  By default
33b90 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
33ba0 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
33bb0 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71 75 65  ROR.  A subseque
33bc0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
33bd0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
33be0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
33bf0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
33c00 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f   resets the erro
33c10 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45  r code to SQLITE
33c20 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68  _ERROR..**.** Th
33c30 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33c40 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
33c50 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
33c60 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
33c70 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
33c80 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
33c90 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20 6c 6f  or BLOB is to lo
33ca0 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
33cb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
33cc0 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28  e3_result_nomem(
33cd0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
33ce0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
33cf0 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
33d00 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
33d10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
33d20 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
33d30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
33d40 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
33d50 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
33d60 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
33d70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33d80 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33d90 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
33da0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
33db0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
33dc0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
33dd0 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ent..** The sqli
33de0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
33df0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
33e00 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
33e10 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
33e20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33e30 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
33e40 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
33e50 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
33e60 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
33e70 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
33e80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
33e90 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
33ea0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
33eb0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
33ec0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
33ed0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33ee0 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
33ef0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
33f00 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
33f10 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
33f20 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
33f30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33f40 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
33f50 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33f60 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
33f70 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
33f80 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
33f90 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33fa0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
33fb0 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
33fc0 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
33fd0 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
33fe0 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
33ff0 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
34000 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
34010 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
34020 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
34030 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 53 51  pectively..** SQ
34040 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
34050 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
34060 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
34070 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
34080 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
34090 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
340a0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
340b0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  ..** If the 3rd 
340c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
340d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
340e0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
340f0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
34100 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
34110 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
34120 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
34130 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
34140 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
34150 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66  character..** If
34160 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
34170 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
34180 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
34190 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
341a0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
341b0 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
341c0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
341d0 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
341e0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
341f0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
34200 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
34210 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34220 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
34230 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  n result..** If 
34240 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
34250 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
34260 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
34270 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
34280 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34290 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
342a0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
342b0 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
342c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
342d0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
342e0 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
342f0 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
34300 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
34310 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
34320 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34  ult..** If the 4
34330 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
34340 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
34350 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
34360 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ces or.** sqlite
34370 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
34380 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
34390 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
343a0 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
343b0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
343c0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
343d0 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
343e0 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
343f0 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
34400 70 79 20 74 68 65 20 69 74 20 6f 72 20 63 61 6c  py the it or cal
34410 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 77  l a destructor w
34420 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
34430 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
34440 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
34450 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
34460 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
34470 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
34480 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
34490 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
344a0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
344b0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
344c0 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
344d0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
344e0 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
344f0 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
34500 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
34510 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
34520 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
34530 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
34540 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34550 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
34560 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
34570 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
34580 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
34590 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
345a0 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
345b0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
345c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
345d0 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
345e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
345f0 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  r.  The.** sqlit
34600 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
34610 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
34620 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
34630 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
34640 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
34650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
34660 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
34670 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
34680 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
34690 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
346a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
346b0 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
346c0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
346d0 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  A [protected sql
346e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
346f0 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65  ct may always be
34700 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a   used where an.*
34710 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
34720 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34730 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64  ject is required
34740 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b  , so either.** k
34750 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ind of [sqlite3_
34760 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61  value] object ca
34770 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74  n be used with t
34780 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
34790 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f  *.** If these ro
347a0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
347b0 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68  d from within th
347c0 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  e different thre
347d0 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f  ad.** than the o
347e0 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ne containing th
347f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34800 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
34810 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20  hat received.** 
34820 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
34830 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74  text] pointer, t
34840 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
34850 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
34860 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
34870 2a 20 7b 48 31 36 34 30 33 7d 20 54 68 65 20 64  * {H16403} The d
34880 65 66 61 75 6c 74 20 72 65 74 75 72 6e 20 76 61  efault return va
34890 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20 53 51 4c  lue from any SQL
348a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 4e 55 4c   function is NUL
348b0 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 36  L..**.** {H16406
348c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
348d0 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
348e0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
348f0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
34900 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
34910 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
34920 43 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 74  C to be a BLOB t
34930 68 61 74 20 69 73 20 4e 20 62 79 74 65 73 0a 2a  hat is N bytes.*
34940 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 6c 65  *          in le
34950 6e 67 74 68 20 61 6e 64 20 77 69 74 68 20 63 6f  ngth and with co
34960 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64 20 74 6f  ntent pointed to
34970 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   by V..**.** {H1
34980 36 34 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  6409} The [sqlit
34990 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
349a0 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
349b0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
349c0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
349d0 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
349e0 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 66 6c  n C to be the fl
349f0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
34a00 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ue V..**.** {H16
34a10 34 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  412} The [sqlite
34a20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 43  3_result_error(C
34a30 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,V,N)] interface
34a40 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
34a50 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
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 61 6e 20 65 78 63  n C to be an exc
34a80 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
34a90 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
34aa0 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
34ab0 5d 20 61 6e 64 20 61 20 55 54 46 2d 38 20 65 72  ] and a UTF-8 er
34ac0 72 6f 72 20 6d 65 73 73 61 67 65 20 63 6f 70 69  ror message copi
34ad0 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20  ed from V up to 
34ae0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
34af0 66 69 72 73 74 20 7a 65 72 6f 20 62 79 74 65 20  first zero byte 
34b00 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65 73  or until N bytes
34b10 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69   are read if N i
34b20 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a  s positive..**.*
34b30 2a 20 7b 48 31 36 34 31 35 7d 20 54 68 65 20 5b  * {H16415} The [
34b40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34b50 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29 5d 20 69  rror16(C,V,N)] i
34b60 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
34b70 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
34b80 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
34b90 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
34ba0 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77  e an exception w
34bb0 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  ith error code.*
34bc0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
34bd0 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20  TE_ERROR] and a 
34be0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
34bf0 74 65 20 6f 72 64 65 72 20 65 72 72 6f 72 20 6d  te order error m
34c00 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20  essage.**       
34c10 20 20 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56     copied from V
34c20 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
34c30 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
34c40 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79 74 65   or until N byte
34c50 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  s.**          ar
34c60 65 20 72 65 61 64 20 69 66 20 4e 20 69 73 20 70  e read if N is p
34c70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  ositive..**.** {
34c80 48 31 36 34 31 38 7d 20 54 68 65 20 5b 73 71 6c  H16418} The [sql
34c90 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34ca0 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20 69 6e 74  r_toobig(C)] int
34cb0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
34cc0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  he return.**    
34cd0 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74        value of t
34ce0 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  he function C to
34cf0 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
34d00 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
34d10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
34d20 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 61 6e 64  LITE_TOOBIG] and
34d30 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
34d40 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
34d50 2a 0a 2a 2a 20 7b 48 31 36 34 32 31 7d 20 54 68  *.** {H16421} Th
34d60 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
34d70 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 43 29  t_error_nomem(C)
34d80 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
34d90 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
34da0 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
34db0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
34dc0 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
34dd0 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
34de0 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
34df0 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d    [SQLITE_NOMEM]
34e00 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69   and an appropri
34e10 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ate error messag
34e20 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 34  e..**.** {H16424
34e30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
34e40 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
34e50 28 43 2c 45 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,E)] interface
34e60 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
34e70 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
34e80 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
34e90 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
34ea0 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
34eb0 65 72 72 6f 72 20 63 6f 64 65 20 45 2e 0a 2a 2a  error code E..**
34ec0 20 20 20 20 20 20 20 20 20 20 54 68 65 20 65 72            The er
34ed0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
34ee0 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
34ef0 2a 0a 2a 2a 20 7b 48 31 36 34 32 37 7d 20 54 68  *.** {H16427} Th
34f00 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
34f10 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69 6e 74 65  t_int(C,V)] inte
34f20 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
34f30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
34f40 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
34f50 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
34f60 68 65 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  he 32-bit intege
34f70 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  r value V..**.**
34f80 20 7b 48 31 36 34 33 30 7d 20 54 68 65 20 5b 73   {H16430} The [s
34f90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
34fa0 74 36 34 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  t64(C,V)] interf
34fb0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
34fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
34fd0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
34fe0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
34ff0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
35000 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
35010 48 31 36 34 33 33 7d 20 54 68 65 20 5b 73 71 6c  H16433} The [sql
35020 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
35030 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
35040 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
35050 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
35060 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
35070 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  C to be NULL..**
35080 0a 2a 2a 20 7b 48 31 36 34 33 36 7d 20 54 68 65  .** {H16436} The
35090 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
350a0 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 20  _text(C,V,N,D)] 
350b0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
350c0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
350d0 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
350e0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
350f0 62 65 20 74 68 65 20 55 54 46 2d 38 20 73 74 72  be the UTF-8 str
35100 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
35110 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
35120 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e  t zero if N is n
35130 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
35140 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74      or the first
35150 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
35160 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
35170 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33  ve..**.** {H1643
35180 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
35190 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
351a0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
351b0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
351c0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
351d0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
351e0 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
351f0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
35200 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20 20  e order.**      
35210 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
35220 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
35230 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
35240 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
35250 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
35260 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73  tes of V if N is
35270 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
35280 2a 0a 2a 2a 20 7b 48 31 36 34 34 32 7d 20 54 68  *.** {H16442} Th
35290 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
352a0 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
352b0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
352c0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
352d0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
352e0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
352f0 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
35300 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a  16 big-endian.**
35310 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
35320 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72   V up to the fir
35330 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20  st zero if N is 
35340 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
35350 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73       or the firs
35360 74 20 4e 20 62 79 74 65 73 20 6f 72 20 56 20 69  t N bytes or V i
35370 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  f N is non-negat
35380 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  ive..**.** {H164
35390 34 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  45} The [sqlite3
353a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
353b0 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
353c0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
353d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
353e0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
353f0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
35400 65 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  e UTF-16 little-
35410 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
35420 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74     string V up t
35430 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
35440 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
35450 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  e.**          or
35460 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74   the first N byt
35470 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20  es of V if N is 
35480 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
35490 0a 2a 2a 20 7b 48 31 36 34 34 38 7d 20 54 68 65  .** {H16448} The
354a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
354b0 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20 69 6e 74  _value(C,V)] int
354c0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
354d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
354e0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
354f0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
35500 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
35510 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
35520 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 6a 65  **          obje
35530 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ct V..**.** {H16
35540 34 35 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  451} The [sqlite
35550 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
35560 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  b(C,N)] interfac
35570 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
35580 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
35590 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
355a0 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 4e 2d  on C to be an N-
355b0 62 79 74 65 20 42 4c 4f 42 20 6f 66 20 61 6c 6c  byte BLOB of all
355c0 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48   zeros..**.** {H
355d0 31 36 34 35 34 7d 20 54 68 65 20 5b 73 71 6c 69  16454} The [sqli
355e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
355f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
35600 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35610 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
35620 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65 20 61  nterfaces make a
35630 20 63 6f 70 79 20 6f 66 20 74 68 65 69 72 20 65   copy of their e
35640 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
35650 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a 2a 20 20  ings before.**  
35660 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 69 6e          returnin
35670 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 37  g..**.** {H16457
35680 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74 72  } If the D destr
35690 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20  uctor parameter 
356a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
356b0 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29  lt_blob(C,V,N,D)
356c0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
356d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
356e0 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b  ext(C,V,N,D)], [
356f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35700 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c  ext16(C,V,N,D)],
35710 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
35720 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35730 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c  t16be(C,V,N,D)],
35740 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
35750 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35760 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
35770 29 5d 20 69 73 20 74 68 65 20 63 6f 6e 73 74 61  )] is the consta
35780 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  nt [SQLITE_STATI
35790 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  C].**          t
357a0 68 65 6e 20 6e 6f 20 64 65 73 74 72 75 63 74 6f  hen no destructo
357b0 72 20 69 73 20 65 76 65 72 20 63 61 6c 6c 65 64  r is ever called
357c0 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74 65 72 20   on the pointer 
357d0 56 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20  V and SQLite.** 
357e0 20 20 20 20 20 20 20 20 20 61 73 73 75 6d 65 73           assumes
357f0 20 74 68 61 74 20 56 20 69 73 20 69 6d 6d 75 74   that V is immut
35800 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  able..**.** {H16
35810 34 36 30 7d 20 49 66 20 74 68 65 20 44 20 64 65  460} If the D de
35820 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
35830 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
35840 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
35850 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
35860 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
35870 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
35880 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
35890 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
358a0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
358b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
358c0 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
358d0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
358e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
358f0 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
35900 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e  N,D)] is the con
35910 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  stant.**        
35920 20 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49    [SQLITE_TRANSI
35930 45 4e 54 5d 20 74 68 65 6e 20 74 68 65 20 69 6e  ENT] then the in
35940 74 65 72 66 61 63 65 73 20 6d 61 6b 65 73 20 61  terfaces makes a
35950 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
35960 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 6e 74           content
35970 20 6f 66 20 56 20 61 6e 64 20 72 65 74 61 69 6e   of V and retain
35980 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a 2a 0a 2a  s the copy..**.*
35990 2a 20 7b 48 31 36 34 36 33 7d 20 49 66 20 74 68  * {H16463} If th
359a0 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70  e D destructor p
359b0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
359c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
359d0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
359e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
359f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56  _result_text(C,V
35a00 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ,N,D)], [sqlite3
35a10 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43  _result_text16(C
35a20 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20  ,V,N,D)],.**    
35a30 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
35a40 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43  esult_text16be(C
35a50 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,N,D)], or.** 
35a60 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
35a70 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
35a80 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 73  e(C,V,N,D)] is s
35a90 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68 65 72 20  ome value other 
35aa0 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
35ab0 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
35ac0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 20 61  SQLITE_STATIC] a
35ad0 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  nd [SQLITE_TRANS
35ae0 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a 20 20 20  IENT] then.**   
35af0 20 20 20 20 20 20 20 53 51 4c 69 74 65 20 77 69         SQLite wi
35b00 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
35b10 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20  structor D with 
35b20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79 20 61 72  V as its only ar
35b30 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  gument.**       
35b40 20 20 20 77 68 65 6e 20 69 74 20 68 61 73 20 66     when it has f
35b50 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
35b60 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a 76 6f 69   V value..*/.voi
35b70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35b80 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
35b90 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
35ba0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
35bb0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
35bc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
35bd0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
35be0 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
35bf0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35c00 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74  sult_error(sqlit
35c10 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
35c20 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a  st char*, int);.
35c30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35c40 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
35c50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
35c60 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
35c70 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35c80 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
35c90 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
35ca0 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
35cb0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
35cc0 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e  omem(sqlite3_con
35cd0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
35ce0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35cf0 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63  r_code(sqlite3_c
35d00 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
35d10 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35d20 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63  lt_int(sqlite3_c
35d30 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
35d40 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35d50 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
35d60 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
35d70 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  e3_int64);.void 
35d80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
35d90 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
35da0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
35db0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
35dc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35dd0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
35de0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
35df0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
35e00 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
35e10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35e20 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
35e30 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
35e40 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
35e50 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
35e60 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
35e70 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
35e80 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
35e90 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
35ea0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35eb0 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
35ec0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
35ed0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
35ee0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
35ef0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
35f00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35f10 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
35f20 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
35f30 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
35f40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35f50 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  *, int n);../*.*
35f60 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69  * CAPI3REF: Defi
35f70 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67  ne New Collating
35f80 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31 36 36   Sequences {H166
35f90 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a  00} <S20300>.**.
35fa0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
35fb0 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ns are used to a
35fc0 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  dd new collation
35fd0 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68   sequences to th
35fe0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
35ff0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
36000 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
36010 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
36020 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
36030 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  e new collation 
36040 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63  sequence is spec
36050 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38  ified as a UTF-8
36060 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
36070 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36080 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
36090 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
360a0 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
360b0 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
360c0 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ng for sqlite3_c
360d0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
360e0 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61 73 65  6(). In all case
360f0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73  s.** the name is
36100 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
36110 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
36120 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  rgument..**.** T
36130 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
36140 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  t may be one of 
36150 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
36160 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
36170 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
36180 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
36190 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6BE], indicating
361a0 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73   that the user-s
361b0 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69  upplied.** routi
361c0 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65  ne expects to be
361d0 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73   passed pointers
361e0 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f   to strings enco
361f0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c  ded using UTF-8,
36200 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
36210 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e-endian, or UTF
36220 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20  -16 big-endian, 
36230 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 54 68  respectively. Th
36240 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d  e.** third argum
36250 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62  ent might also b
36260 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
36270 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69 6e 64 69  ALIGNED] to indi
36280 63 61 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  cate that.** the
36290 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
362a0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d   pointers to 16-
362b0 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64  bit word aligned
362c0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55   strings.** of U
362d0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
362e0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 6f  ive byte order o
362f0 66 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75  f the host compu
36300 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  ter..**.** A poi
36310 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72  nter to the user
36320 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e   supplied routin
36330 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  e must be passed
36340 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a   as the fifth.**
36350 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20 69   argument.  If i
36360 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20  t is NULL, this 
36370 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64  is the same as d
36380 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c  eleting the coll
36390 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
363a0 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74  e (so that SQLit
363b0 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74  e cannot call it
363c0 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61   anymore)..** Ea
363d0 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c  ch time the appl
363e0 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64  ication supplied
363f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
36400 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
36410 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72  ed.** as its fir
36420 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 63  st parameter a c
36430 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
36440 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
36450 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
36460 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  * to sqlite3_cre
36470 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
36480 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
36490 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
364a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  .**.** The remai
364b0 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74  ning arguments t
364c0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
364d0 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  n-supplied routi
364e0 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e  ne are two strin
364f0 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72  gs,.** each repr
36500 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65  esented by a (le
36510 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72  ngth, data) pair
36520 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20   and encoded in 
36530 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  the encoding.** 
36540 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20  that was passed 
36550 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  as the third arg
36560 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63  ument when the c
36570 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
36580 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65  e was.** registe
36590 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20  red. {END}  The 
365a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
365b0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f  ned collation ro
365c0 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20  utine should.** 
365d0 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c  return negative,
365e0 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76   zero or positiv
365f0 65 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  e if the first s
36600 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
36610 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c  an,.** equal to,
36620 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
36630 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69   the second stri
36640 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47  ng. i.e. (STRING
36650 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a  1 - STRING2)..**
36660 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
36670 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36680 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
36690 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
366a0 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65  collation().** e
366b0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74 61  xcept that it ta
366c0 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67  kes an extra arg
366d0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
366e0 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a   destructor for.
366f0 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ** the collation
36700 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
36710 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e  r is called when
36720 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
36730 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61  s.** destroyed a
36740 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63  nd is passed a c
36750 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74  opy of the fourt
36760 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64  h parameter void
36770 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20  * pointer.** of 
36780 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
36790 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
367a0 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73  )..** Collations
367b0 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
367c0 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
367d0 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
367e0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
367f0 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
36800 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
36810 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62   when the [datab
36820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36830 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69  is closed.** usi
36840 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
36850 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  e()]..**.** INVA
36860 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
36870 31 36 36 30 33 7d 20 41 20 73 75 63 63 65 73 73  16603} A success
36880 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a  ful call to the.
36890 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
368a0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
368b0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
368c0 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,D)] interface
368d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
368e0 69 73 74 65 72 73 20 66 75 6e 63 74 69 6f 6e 20  isters function 
368f0 46 20 61 73 20 74 68 65 20 63 6f 6d 70 61 72 69  F as the compari
36900 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 75 73 65  son function use
36910 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  d to.**         
36920 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f 6c 6c 61   implement colla
36930 74 69 6f 6e 20 58 20 6f 6e 20 74 68 65 20 5b 64  tion X on the [d
36940 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36950 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20 20 20 20  on] B for.**    
36960 20 20 20 20 20 20 64 61 74 61 62 61 73 65 73 20        databases 
36970 68 61 76 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20  having encoding 
36980 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 34  E..**.** {H16604
36990 7d 20 53 51 4c 69 74 65 20 75 6e 64 65 72 73 74  } SQLite underst
369a0 61 6e 64 73 20 74 68 65 20 58 20 70 61 72 61 6d  ands the X param
369b0 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
369c0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
369d0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
369e0 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 61  (B,X,E,P,F,D)] a
369f0 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
36a00 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
36a10 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 20  UTF-8 string in 
36a20 77 68 69 63 68 20 63 61 73 65 20 69 73 20 69 67  which case is ig
36a30 6e 6f 72 65 64 20 66 6f 72 20 41 53 43 49 49 20  nored for ASCII 
36a40 63 68 61 72 61 63 74 65 72 73 20 61 6e 64 0a 2a  characters and.*
36a50 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 73 69  *          is si
36a60 67 6e 69 66 69 63 61 6e 74 20 66 6f 72 20 6e 6f  gnificant for no
36a70 6e 2d 41 53 43 49 49 20 63 68 61 72 61 63 74 65  n-ASCII characte
36a80 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30  rs..**.** {H1660
36a90 36 7d 20 53 75 63 63 65 73 73 69 76 65 20 63 61  6} Successive ca
36aa0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
36ab0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36ac0 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
36ad0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
36ae0 74 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  th the same valu
36af0 65 73 20 66 6f 72 20 42 2c 20 58 2c 20 61 6e 64  es for B, X, and
36b00 20 45 2c 20 6f 76 65 72 72 69 64 65 20 70 72 69   E, override pri
36b10 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  or values.**    
36b20 20 20 20 20 20 20 6f 66 20 50 2c 20 46 2c 20 61        of P, F, a
36b30 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  nd D..**.** {H16
36b40 36 30 39 7d 20 49 66 20 74 68 65 20 64 65 73 74  609} If the dest
36b50 72 75 63 74 6f 72 20 44 20 69 6e 20 5b 73 71 6c  ructor D in [sql
36b60 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36b70 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
36b80 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
36b90 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74     is not NULL t
36ba0 68 65 6e 20 69 74 20 69 73 20 63 61 6c 6c 65 64  hen it is called
36bb0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50   with argument P
36bc0 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   when the.**    
36bd0 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
36be0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
36bf0 70 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ped by SQLite..*
36c00 2a 0a 2a 2a 20 7b 48 31 36 36 31 32 7d 20 41 20  *.** {H16612} A 
36c10 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36c20 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68  on is dropped wh
36c30 65 6e 20 69 74 20 69 73 20 6f 76 65 72 6c 6f 61  en it is overloa
36c40 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  ded..**.** {H166
36c50 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  15} A collating 
36c60 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70  function is drop
36c70 70 65 64 20 77 68 65 6e 20 74 68 65 20 64 61 74  ped when the dat
36c80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36c90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
36ca0 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
36cb0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
36cc0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 38 7d 20 54  **.** {H16618} T
36cd0 68 65 20 70 6f 69 6e 74 65 72 20 50 20 69 6e 20  he pointer P in 
36ce0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36cf0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58  collation_v2(B,X
36d00 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20  ,E,P,F,D)].**   
36d10 20 20 20 20 20 20 20 69 73 20 70 61 73 73 65 64         is passed
36d20 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
36d30 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
36d40 74 6f 20 74 68 65 20 63 6f 6d 70 61 72 69 73 6f  to the compariso
36d50 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  n.**          fu
36d60 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
36d70 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
36d80 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e 0a 2a 2a  cations of F..**
36d90 0a 2a 2a 20 7b 48 31 36 36 32 31 7d 20 41 20 63  .** {H16621} A c
36da0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
36db0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36dc0 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 69 73 20  (B,X,E,P,F)] is 
36dd0 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20  exactly.**      
36de0 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73 20      the same as 
36df0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
36e00 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36e10 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74 68 0a 2a  ion_v2()] with.*
36e20 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73  *          the s
36e30 61 6d 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  ame parameters a
36e40 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73 74 72 75  nd a NULL destru
36e50 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ctor..**.** {H16
36e60 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e 67 20 61  624} Following a
36e70 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36e80 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
36e90 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a 2a 2a 20  X,E,P,F,D)],.** 
36ea0 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65 20           SQLite 
36eb0 75 73 65 73 20 74 68 65 20 63 6f 6d 70 61 72 69  uses the compari
36ec0 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 46 20 66  son function F f
36ed0 6f 72 20 61 6c 6c 20 74 65 78 74 20 63 6f 6d 70  or all text comp
36ee0 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
36ef0 20 20 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e     operations on
36f00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
36f10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 6f 6e 20  onnection] B on 
36f20 74 65 78 74 20 76 61 6c 75 65 73 20 74 68 61 74  text values that
36f30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65  .**          use
36f40 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 73   the collating s
36f50 65 71 75 65 6e 63 65 20 6e 61 6d 65 64 20 58 2e  equence named X.
36f60 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 37 7d 20  .**.** {H16627} 
36f70 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
36f80 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
36f90 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77 6f 72 6b  B,X,E,P,F)] work
36fa0 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  s the same.**   
36fb0 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69 74         as [sqlit
36fc0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36fd0 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20  ion(B,X,E,P,F)] 
36fe0 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 0a  except that the.
36ff0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c  **          coll
37000 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 20  ation name X is 
37010 75 6e 64 65 72 73 74 6f 6f 64 20 61 73 20 55 54  understood as UT
37020 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62  F-16 in native b
37030 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20  yte order.**    
37040 20 20 20 20 20 20 69 6e 73 74 65 61 64 20 6f 66        instead of
37050 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
37060 31 36 36 33 30 7d 20 57 68 65 6e 20 6d 75 6c 74  16630} When mult
37070 69 70 6c 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20  iple comparison 
37080 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 76  functions are av
37090 61 69 6c 61 62 6c 65 20 66 6f 72 20 74 68 65 20  ailable for the 
370a0 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
370b0 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65   collating seque
370c0 6e 63 65 2c 20 53 51 4c 69 74 65 20 63 68 6f 6f  nce, SQLite choo
370d0 73 65 73 20 74 68 65 20 6f 6e 65 20 77 68 6f 73  ses the one whos
370e0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  e text encoding.
370f0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 71 75  **          requ
37100 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  ires the least a
37110 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76 65 72 73  mount of convers
37120 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20 64 65 66  ion from the def
37130 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ault.**         
37140 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f   text encoding o
37150 66 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  f the database..
37160 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
37170 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
37180 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
37190 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
371a0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
371b0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
371c0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
371d0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
371e0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
371f0 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
37200 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37210 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
37220 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
37230 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
37240 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
37250 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
37260 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
37270 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
37280 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
37290 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
372a0 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  )(void*).);.int 
372b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
372c0 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
372d0 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
372e0 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
372f0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
37300 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
37310 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
37320 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
37330 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
37340 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37350 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
37360 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 20 7b  eded Callbacks {
37370 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30 30 3e  H16700} <S20300>
37380 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  .**.** To avoid 
37390 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
373a0 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
373b0 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
373c0 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
373d0 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
373e0 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
373f0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
37400 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
37410 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
37420 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
37430 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65 76 65  e called wheneve
37440 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
37450 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
37460 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
37470 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
37480 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
37490 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
374a0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
374b0 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
374c0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
374d0 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
374e0 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
374f0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
37500 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
37510 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
37520 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71 6c 69  {H16703} If sqli
37530 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37540 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64  eded16() is used
37550 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61  ,.** the names a
37560 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46  re passed as UTF
37570 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e  -16 in machine n
37580 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
37590 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 65  ..** A call to e
375a0 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
375b0 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78 69 73  eplaces any exis
375c0 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  ting callback..*
375d0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
375e0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
375f0 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
37600 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
37610 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
37620 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
37630 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
37640 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
37650 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
37660 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
37670 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
37680 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
37690 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
376a0 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
376b0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
376c0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
376d0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
376e0 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
376f0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
37700 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
37710 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
37720 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
37730 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
37740 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
37750 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
37760 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
37770 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
37780 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
37790 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a 2a 20  sequence..**.** 
377a0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
377b0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
377c0 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
377d0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
377e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
377f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
37800 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
37810 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
37820 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
37830 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37840 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  on_v2()]..**.** 
37850 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
37860 2a 20 7b 48 31 36 37 30 32 7d 20 41 20 73 75 63  * {H16702} A suc
37870 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
37880 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
37890 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50 2c 46 29  on_needed(D,P,F)
378a0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
378b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
378c0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 44 2c 50  ion_needed16(D,P
378d0 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a 2a 20 20  ,F)] causes.**  
378e0 20 20 20 20 20 20 20 20 74 68 65 20 5b 64 61 74          the [dat
378f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37900 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65 20 63 61  ] D to invoke ca
37910 6c 6c 62 61 63 6b 20 46 20 77 69 74 68 20 66 69  llback F with fi
37920 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rst.**          
37930 70 61 72 61 6d 65 74 65 72 20 50 20 77 68 65 6e  parameter P when
37940 65 76 65 72 20 69 74 20 6e 65 65 64 73 20 61 20  ever it needs a 
37950 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74  comparison funct
37960 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20 20 20 20  ion for a.**    
37970 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
37980 73 65 71 75 65 6e 63 65 20 74 68 61 74 20 69 74  sequence that it
37990 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f 77 20 61   does not know a
379a0 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  bout..**.** {H16
379b0 37 30 34 7d 20 45 61 63 68 20 73 75 63 63 65 73  704} Each succes
379c0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
379d0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
379e0 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a 2a 2a 20  needed()] or.** 
379f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
37a00 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37a10 65 64 31 36 28 29 5d 20 6f 76 65 72 72 69 64 65  ed16()] override
37a20 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  s the callback r
37a30 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20  egistered.**    
37a40 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d        on the sam
37a50 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37a60 65 63 74 69 6f 6e 5d 20 62 79 20 70 72 69 6f 72  ection] by prior
37a70 20 63 61 6c 6c 73 20 74 6f 20 65 69 74 68 65 72   calls to either
37a80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
37a90 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  erface..**.** {H
37aa0 31 36 37 30 36 7d 20 54 68 65 20 6e 61 6d 65 20  16706} The name 
37ab0 6f 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  of the requested
37ac0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
37ad0 69 6f 6e 20 70 61 73 73 65 64 20 69 6e 20 74 68  ion passed in th
37ae0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 34 74  e.**          4t
37af0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
37b00 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
37b10 6e 20 55 54 46 2d 38 20 69 66 20 74 68 65 20 63  n UTF-8 if the c
37b20 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
37b30 20 20 20 20 77 61 73 20 72 65 67 69 73 74 65 72      was register
37b40 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
37b50 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37b60 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ed()] and.**    
37b70 20 20 20 20 20 20 69 73 20 69 6e 20 55 54 46 2d        is in UTF-
37b80 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
37b90 72 64 65 72 20 69 66 20 74 68 65 20 63 61 6c 6c  rder if the call
37ba0 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20 20 20 20  back was.**     
37bb0 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20       registered 
37bc0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
37bd0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
37be0 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
37bf0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
37c00 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33  eeded(.  sqlite3
37c10 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20  *, .  void*, .  
37c20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
37c30 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
37c40 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  Rep,const char*)
37c50 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
37c60 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37c70 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
37c80 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64  .  void*,.  void
37c90 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
37ca0 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
37cb0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
37cc0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
37cd0 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
37ce0 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
37cf0 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
37d00 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
37d10 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
37d20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
37d30 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
37d40 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
37d50 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
37d60 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
37d70 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
37d80 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
37d90 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20   sqlite3_key(.  
37da0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
37db0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
37dc0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
37dd0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
37de0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
37df0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
37e00 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  The key */.);../
37e10 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20  *.** Change the 
37e20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64  key on an open d
37e30 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65  atabase.  If the
37e40 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
37e50 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72  e is not.** encr
37e60 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74  ypted, this rout
37e70 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74  ine will encrypt
37e80 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30   it.  If pNew==0
37e90 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65   or nNew==0, the
37ea0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20  .** database is 
37eb0 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a  decrypted..**.**
37ec0 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
37ed0 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
37ee0 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
37ef0 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
37f00 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
37f10 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
37f20 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c  te3_rekey(.  sql
37f30 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
37f40 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
37f50 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
37f60 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
37f70 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
37f80 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
37f90 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   new key */.);..
37fa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37fb0 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f  Suspend Executio
37fc0 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69  n For A Short Ti
37fd0 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c 53 34 30  me {H10530} <S40
37fe0 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  410>.**.** The s
37ff0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
38000 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
38010 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
38020 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
38030 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
38040 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
38050 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
38060 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
38070 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
38080 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
38090 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
380a0 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
380b0 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
380c0 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
380d0 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
380e0 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
380f0 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
38100 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
38110 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
38120 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
38130 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
38140 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
38150 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
38160 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
38170 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
38180 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
38190 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
381a0 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
381b0 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
381c0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
381d0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
381e0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
381f0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
38200 20 7b 48 31 30 35 33 33 7d 20 54 68 65 20 5b 73   {H10533} The [s
38210 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d  qlite3_sleep(M)]
38220 20 69 6e 74 65 72 66 61 63 65 20 69 6e 76 6f 6b   interface invok
38230 65 73 20 74 68 65 20 78 53 6c 65 65 70 0a 2a 2a  es the xSleep.**
38240 20 20 20 20 20 20 20 20 20 20 6d 65 74 68 6f 64            method
38250 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
38260 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c 56 46 53  [sqlite3_vfs|VFS
38270 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ] in order to.**
38280 20 20 20 20 20 20 20 20 20 20 73 75 73 70 65 6e            suspen
38290 64 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  d execution of t
382a0 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
382b0 64 20 66 6f 72 20 61 74 20 6c 65 61 73 74 0a 2a  d for at least.*
382c0 2a 20 20 20 20 20 20 20 20 20 20 4d 20 6d 69 6c  *          M mil
382d0 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a  liseconds..**.**
382e0 20 7b 48 31 30 35 33 36 7d 20 54 68 65 20 5b 73   {H10536} The [s
382f0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 4d 29 5d  qlite3_sleep(M)]
38300 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
38310 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
38320 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 69 6c  .**          mil
38330 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
38340 65 70 20 61 63 74 75 61 6c 6c 79 20 72 65 71 75  ep actually requ
38350 65 73 74 65 64 20 6f 66 20 74 68 65 20 6f 70 65  ested of the ope
38360 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  rating.**       
38370 20 20 20 73 79 73 74 65 6d 2c 20 77 68 69 63 68     system, which
38380 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72   might be larger
38390 20 74 68 61 6e 20 74 68 65 20 70 61 72 61 6d 65   than the parame
383a0 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ter M..*/.int sq
383b0 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
383c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
383d0 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  F: Name Of The F
383e0 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
383f0 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 48  mporary Files {H
38400 31 30 33 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a  10310} <S20000>.
38410 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c  **.** If this gl
38420 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
38430 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
38440 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
38450 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
38460 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
38470 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
38480 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61  then all tempora
38490 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61  ry files.** crea
384a0 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69  ted by SQLite wi
384b0 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
384c0 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20  that directory. 
384d0 20 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   If this variabl
384e0 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  e.** is a NULL p
384f0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
38500 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73  ite performs a s
38510 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
38520 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70  ropriate.** temp
38530 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63  orary file direc
38540 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tory..**.** It i
38550 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 6d 6f  s not safe to mo
38560 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
38570 6c 65 20 6f 6e 63 65 20 61 20 5b 64 61 74 61 62  le once a [datab
38580 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
38590 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f 70 65 6e  ** has been open
385a0 65 64 2e 20 20 49 74 20 69 73 20 69 6e 74 65 6e  ed.  It is inten
385b0 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
385c0 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
385d0 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
385e0 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
385f0 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
38600 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
38610 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
38620 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
38630 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e 20 75 6e  ll and remain un
38640 63 68 61 6e 67 65 64 20 74 68 65 72 65 61 66 74  changed thereaft
38650 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  er..*/.SQLITE_EX
38660 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
38670 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
38680 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
38690 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74  EF: Test For Aut
386a0 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48  o-Commit Mode {H
386b0 31 32 39 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a  12930} <S60200>.
386c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75  ** KEYWORDS: {au
386d0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a  tocommit mode}.*
386e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
386f0 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
38700 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
38710 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
38720 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
38730 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
38740 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
38750 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
38760 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
38770 70 65 63 74 69 76 65 6c 79 2e 20 20 41 75 74 6f  pectively.  Auto
38780 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
38790 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  n by default..**
387a0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
387b0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
387c0 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  a [BEGIN] statem
387d0 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d  ent..** Autocomm
387e0 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e  it mode is re-en
387f0 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d  abled by a [COMM
38800 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
38810 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74  ]..**.** If cert
38820 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72  ain kinds of err
38830 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73  ors occur on a s
38840 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
38850 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e  a multi-statemen
38860 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  t.** transaction
38870 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69   (errors includi
38880 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d  ng [SQLITE_FULL]
38890 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  , [SQLITE_IOERR]
388a0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ,.** [SQLITE_NOM
388b0 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  EM], [SQLITE_BUS
388c0 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  Y], and [SQLITE_
388d0 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e  INTERRUPT]) then
388e0 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74   th