/ Hex Artifact Content
Login

Artifact f13b2f27265b78226240cb0d2e07f165e2110bd9:


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 31 37 20 32 30 30 38 2f 31  n,v 1.417 2008/1
05f0: 32 2f 30 38 20 31 38 3a 31 39 3a 31 38 20 64 72  2/08 18:19: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 23 64  RR | (15<<8)).#d
5630: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5640: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5650: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5660: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5670: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5680: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5690: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
56a0: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 0a 2f  RR | (17<<8))../
56b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
56c0: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
56d0: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48  en Operations {H
56e0: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20  10230} <H11120> 
56f0: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12700>.**.** T
5700: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
5710: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
5720: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
5730: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
5740: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
5750: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
5760: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
5770: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
5780: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
5790: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
57a0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
57b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
57c0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
57d0: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
57e0: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
57f0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
5800: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
5810: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5820: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
5830: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5840: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
5850: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
5860: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
5870: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
5880: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
5890: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
58a0: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
58b0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
58c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
58d0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
58e0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
58f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5900: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
5910: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
5920: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
5930: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
5940: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
5950: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5960: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
5970: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
5980: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5990: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
59a0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
59b0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
59c0: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  2000.#define SQL
59d0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
59e0: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
59f0: 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  4000.#define SQL
5a00: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
5a10: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a20: 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  8000.#define SQL
5a30: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
5a40: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
5a50: 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0000../*.** CAPI
5a60: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5a70: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
5a80: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
5a90: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5aa0: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
5ab0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
5ac0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
5ad0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
5ae0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
5af0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5b00: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5b10: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5b20: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5b30: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5b40: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5b50: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5b60: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5b70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5b80: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5b90: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
5ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5bb0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
5bc0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
5bd0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
5be0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
5bf0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5c00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5c10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5c20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5c30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5c40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5c50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5c60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5c70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5c80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5c90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
5ca0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5cb0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
5cc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
5cd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
5ce0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
5cf0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5d00: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5d10: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5d20: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5d30: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5d40: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5d50: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5d60: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5d70: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5d80: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5d90: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
5da0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
5db0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
5dc0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
5dd0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
5de0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5df0: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
5e00: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5e10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e20: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
5e30: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
5e40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e50: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
5e60: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
5e70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e80: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
5e90: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
5ea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5eb0: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
5ec0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5ed0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ee0: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
5ef0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
5f00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f10: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
5f20: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
5f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f40: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
5f50: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
5f60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f70: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
5f80: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
5f90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5fa0: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
5fb0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
5fc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
5fd0: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
5fe0: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
5ff0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6000: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
6010: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
6020: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
6030: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
6040: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6050: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6060: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
6070: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
6080: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
6090: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
60a0: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
60b0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
60c0: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
60d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
60e0: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
60f0: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
6100: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
6110: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
6120: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6130: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
6140: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
6150: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
6160: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6170: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
6180: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
6190: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
61a0: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
61b0: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
61c0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
61d0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
61e0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
61f0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6200: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6210: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
6220: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
6230: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6240: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6250: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
6260: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
6270: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6280: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
6290: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
62a0: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
62b0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
62c0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
62d0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
62e0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
62f0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
6300: 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54  ushed. The SQLIT
6310: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c  E_SYNC_NORMAL fl
6320: 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  ag means.** to u
6330: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
6340: 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65  ) semantics. The
6350: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6360: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20  L flag means.** 
6370: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
6380: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
6390: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
63a0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
63b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
63c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
63d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
63e0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
63f0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
6400: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6410: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
6420: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
6430: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
6440: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
6450: 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30  le {H11110} <S20
6460: 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  110>.**.** An [s
6470: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6480: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
6490: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
64a0: 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61  he OS.** interfa
64b0: 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76  ce layer.  Indiv
64c0: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
64d0: 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ce implementatio
64e0: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
64f0: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
6500: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
6510: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
6520: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
6530: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
6540: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
6550: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
6560: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6570: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6580: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
6590: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
65a0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
65b0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
65c0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
65d0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
65e0: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
65f0: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
6600: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
6610: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
6620: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
6630: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
6640: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
6650: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
6660: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6670: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
6680: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
6690: 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30 7d   Object {H11120}
66a0: 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S20110>.**.** 
66b0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
66c0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
66d0: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74  3_vfs] xOpen met
66e0: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
66f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
6700: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
6710: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
6720: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
6730: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
6740: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
6750: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
6760: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
6770: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
6780: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
6790: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
67a0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
67b0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
67c0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
67d0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
67e0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
67f0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
6800: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
6810: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
6820: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
6830: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
6840: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
6850: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
6860: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
6870: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
6880: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
6890: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
68a0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
68b0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
68c0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
68d0: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
68e0: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
68f0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
6900: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
6910: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
6920: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
6930: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
6940: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
6950: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
6960: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
6970: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
6980: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6990: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
69a0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
69b0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
69c0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
69d0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
69e0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
69f0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
6a00: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
6a10: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
6a20: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
6a30: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
6a40: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
6a50: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
6a60: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
6a70: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
6a80: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
6a90: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
6aa0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
6ab0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
6ac0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
6ad0: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
6ae0: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
6af0: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
6b00: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
6b10: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
6b20: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
6b30: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
6b40: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
6b50: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
6b60: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
6b70: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
6b80: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
6b90: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
6ba0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
6bb0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
6bc0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
6bd0: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
6be0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
6bf0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
6c00: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
6c10: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
6c20: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
6c30: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
6c40: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
6c50: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
6c60: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
6c70: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
6c80: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
6c90: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
6ca0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
6cb0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
6cc0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
6cd0: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
6ce0: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
6cf0: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
6d00: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
6d10: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
6d20: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
6d30: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
6d40: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
6d50: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
6d60: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
6d70: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
6d80: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
6d90: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
6da0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
6db0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
6dc0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
6dd0: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
6de0: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
6df0: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
6e00: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
6e10: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
6e20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
6e30: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
6e40: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
6e50: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
6e60: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
6e70: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
6e80: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
6e90: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
6ea0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
6eb0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
6ec0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
6ed0: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nflicts..**.** T
6ee0: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
6ef0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6f00: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
6f10: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
6f20: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
6f30: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
6f40: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
6f50: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
6f60: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
6f70: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
6f80: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
6f90: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
6fa0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
6fb0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6fc0: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
6fd0: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
6fe0: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
6ff0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
7000: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
7010: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
7020: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7030: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
7040: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7050: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
7060: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7070: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
7080: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7090: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
70a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
70c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
70e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
70f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
7100: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7110: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
7120: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
7130: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
7140: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7150: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
7160: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
7170: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
7180: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
7190: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
71a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
71b0: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
71c0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
71d0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
71e0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
71f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7200: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
7210: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
7220: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
7230: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
7240: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
7250: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
7260: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
7270: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
7280: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
7290: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
72a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
72b0: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
72c0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
72d0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
72e0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
72f0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
7300: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
7310: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
7320: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
7330: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
7340: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
7350: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
7360: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
7370: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
7380: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
7390: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
73a0: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
73b0: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
73c0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
73d0: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
73e0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
73f0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
7400: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
7410: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
7420: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
7430: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
7440: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
7450: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
7460: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
7470: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
7480: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
7490: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
74a0: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
74b0: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
74c0: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
74d0: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
74e0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
74f0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7500: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
7510: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
7520: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
7530: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
7540: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
7550: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
7560: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
7570: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
7580: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
7590: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
75a0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
75b0: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
75c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
75d0: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
75e0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
75f0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
7600: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
7610: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
7620: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
7630: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
7640: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7650: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
7660: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
7670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
7680: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
7690: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
76a0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
76b0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
76c0: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
76d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
76e0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
76f0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
7700: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
7710: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
7720: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
7730: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7740: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
7750: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
7760: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
7770: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
7780: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
7790: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
77a0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64  _file*);.  /* Ad
77b0: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
77c0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
77d0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
77e0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
77f0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
7800: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
7810: 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d 20 3c  codes {H11310} <
7820: 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30800>.**.** Th
7830: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
7840: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
7850: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
7860: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
7870: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
7880: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7890: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
78a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
78b0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
78c0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
78d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
78e0: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
78f0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
7900: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
7910: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
7920: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
7930: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
7940: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
7950: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
7960: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
7970: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
7980: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7990: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
79a0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
79b0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
79c0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
79d0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
79e0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
79f0: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
7a00: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
7a10: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
7a20: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
7a30: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
7a40: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
7a50: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
7a60: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
7a70: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
7a80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7a90: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
7aa0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
7ab0: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
7ac0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
7ad0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7ae0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
7af0: 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  LE      3.#defin
7b00: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
7b10: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
7b20: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
7b30: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20  F: Mutex Handle 
7b40: 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31 33 30  {H17110} <S20130
7b50: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  >.**.** The mute
7b60: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
7b70: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
7b80: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
7b90: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
7ba0: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
7bb0: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
7bc0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
7bd0: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
7be0: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
7bf0: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
7c00: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
7c10: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
7c20: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
7c30: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
7c40: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
7c50: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
7c60: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
7c70: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
7c80: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
7c90: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7ca0: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
7cb0: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
7cc0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7cd0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b  terface Object {
7ce0: 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30 30 3e  H11140} <S20100>
7cf0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
7d00: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
7d10: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
7d20: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
7d30: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
7d40: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
7d50: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
7d60: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7d70: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
7d80: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
7d90: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
7da0: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
7db0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a  ile system"..**.
7dc0: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
7dd0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
7de0: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
7df0: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
7e00: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
7e10: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
7e20: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
7e30: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
7e40: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
7e50: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
7e60: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
7e70: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
7e80: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
7e90: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
7ea0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
7eb0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
7ec0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
7ed0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
7ee0: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
7ef0: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
7f00: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
7f10: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
7f20: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
7f30: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
7f40: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
7f50: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
7f60: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
7f70: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
7f80: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
7f90: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
7fa0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
7fb0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
7fc0: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
7fd0: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
7fe0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
7ff0: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
8000: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
8010: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
8020: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
8030: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
8040: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
8050: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
8060: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
8070: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
8080: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
8090: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
80a0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
80b0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
80c0: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
80d0: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
80e0: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
80f0: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
8100: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
8110: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
8120: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
8130: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
8140: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
8150: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
8160: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
8170: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
8180: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
8190: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
81a0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
81b0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
81c0: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
81d0: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
81e0: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
81f0: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
8200: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
8210: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
8220: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
8230: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
8240: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
8250: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
8260: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
8270: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
8280: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
8290: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
82a0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
82b0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
82c0: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
82d0: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
82e0: 7b 48 31 31 31 34 31 7d 20 53 51 4c 69 74 65 20  {H11141} SQLite 
82f0: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74  will guarantee t
8300: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
8310: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
8320: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
8330: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
8340: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
8350: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
8360: 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53 51  lPathname().  SQ
8370: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
8380: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
8390: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
83a0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
83b0: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
83c0: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
83d0: 65 64 2e 20 7b 45 4e 44 7d 20 20 42 65 63 61 75  ed. {END}  Becau
83e0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
83f0: 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a 2a 20  us sentense,.** 
8400: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8410: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
8420: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
8430: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
8440: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
8450: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
8460: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
8470: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
8480: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
8490: 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 69 73  eter is xOpen is
84a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
84b0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
84c0: 73 74 20 69 6e 76 69 74 65 20 69 74 73 20 6f 77  st invite its ow
84d0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
84e0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
84f0: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
8500: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
8510: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
8520: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
8530: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
8540: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
8550: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
8560: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8570: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
8580: 2a 20 7b 48 31 31 31 34 32 7d 20 54 68 65 20 66  * {H11142} The f
8590: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
85a0: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
85b0: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
85c0: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
85d0: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
85e0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
85f0: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
8600: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
8610: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
8620: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
8630: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
8640: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
8650: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
8660: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
8670: 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44 7d 0a  _CREATE]. {END}.
8680: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
8690: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
86a0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
86b0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
86c0: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
86d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
86e0: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
86f0: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
8700: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b   be set..**.** {
8710: 48 31 31 31 34 33 7d 20 53 51 4c 69 74 65 20 77  H11143} SQLite w
8720: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
8730: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
8740: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
8750: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
8760: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
8770: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
8780: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
8790: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
87a0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
87b0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
87c0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
87d0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
87e0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
87f0: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
8800: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
8810: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
8820: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
8830: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
8840: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8850: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
8860: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8870: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
8880: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44  L].** </ul> {END
8890: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  }.**.** The file
88a0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
88b0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
88c0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
88d0: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
88e0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
88f0: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
8900: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
8910: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
8920: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
8930: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
8940: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
8950: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
8960: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
8970: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
8980: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
8990: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
89a0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
89b0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
89c0: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
89d0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
89e0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
89f0: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
8a00: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
8a10: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
8a20: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
8a30: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
8a40: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
8a50: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
8a60: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
8a70: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
8a80: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
8a90: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
8aa0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
8ab0: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
8ac0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
8ad0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
8ae0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
8af0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8b00: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
8b10: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8b20: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8b30: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
8b40: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
8b50: 7b 48 31 31 31 34 35 7d 20 54 68 65 20 5b 53 51  {H11145} The [SQ
8b60: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8b70: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
8b80: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
8b90: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
8ba0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
8bb0: 73 65 64 2e 20 20 7b 48 31 31 31 34 36 7d 20 54  sed.  {H11146} T
8bc0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
8bd0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
8be0: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
8bf0: 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73 65  r TEMP  database
8c00: 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20  s, journals and 
8c10: 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  for subjournals.
8c20: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 37 7d 20  .**.** {H11147} 
8c30: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8c40: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
8c50: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
8c60: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
8c70: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
8c80: 65 20 61 63 63 65 73 73 2e 20 20 54 68 69 73 20  e access.  This 
8c90: 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72 20  flag is set for 
8ca0: 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74  all files except
8cb0: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e  .** for the main
8cc0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
8cd0: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 38 7d 20 41  **.** {H11148} A
8ce0: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
8cf0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
8d00: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
8d10: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
8d20: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
8d30: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
8d40: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
8d50: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
8d60: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 7b 45 4e 44  t to xOpen. {END
8d70: 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  }  The xOpen met
8d80: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
8d90: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
8da0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
8db0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
8dc0: 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a  ill it in..**.**
8dd0: 20 7b 48 31 31 31 34 39 7d 20 54 68 65 20 66 6c   {H11149} The fl
8de0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
8df0: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
8e00: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
8e10: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
8e20: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
8e30: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
8e40: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8e50: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
8e60: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
8e70: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
8e80: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
8e90: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
8ea0: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
8eb0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
8ec0: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
8ed0: 65 61 64 61 62 6c 65 2e 20 7b 45 4e 44 7d 20 20  eadable. {END}  
8ee0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
8ef0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
8f00: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 35 30 7d 20 53  **.** {H11150} S
8f10: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
8f20: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
8f30: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
8f40: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
8f50: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
8f60: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 7b  xFullPathname. {
8f70: 48 31 31 31 35 31 7d 20 54 68 65 20 65 78 61 63  H11151} The exac
8f80: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
8f90: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
8fa0: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
8fb0: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
8fc0: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 7b  both  methods. {
8fd0: 45 4e 44 7d 20 20 49 66 20 74 68 65 20 6f 75 74  END}  If the out
8fe0: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
8ff0: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
9000: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
9010: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
9020: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
9030: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
9040: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
9050: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
9060: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
9070: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
9080: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
9090: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
90a0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
90b0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
90c0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
90d0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
90e0: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64  ), xSleep(), and
90f0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
9100: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
9110: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
9120: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
9130: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
9140: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
9150: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
9160: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
9170: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
9180: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
9190: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
91a0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
91b0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
91c0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
91d0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
91e0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
91f0: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
9200: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
9210: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
9220: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
9230: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
9240: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
9250: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
9260: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
9270: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
9280: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
9290: 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75 72  given.  The xCur
92a0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
92b0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
92c0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
92d0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
92e0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 2e 0a   date and time..
92f0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
9300: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
9310: 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63  lite3_vfs;.struc
9320: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
9330: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
9340: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
9350: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
9360: 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20  number */.  int 
9370: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
9380: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
9390: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
93a0: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
93b0: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
93c0: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
93d0: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
93e0: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
93f0: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
9400: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
9410: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
9420: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
9430: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
9440: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
9450: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
9460: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
9470: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
9480: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
9490: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
94a0: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
94b0: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
94c0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
94d0: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
94e0: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
94f0: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
9500: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
9510: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
9520: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9530: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
9540: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
9550: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
9560: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9570: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
9580: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
9590: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
95a0: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
95b0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
95c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
95d0: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
95e0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
95f0: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
9600: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
9610: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
9620: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
9630: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
9640: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
9650: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
9660: 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79    void (*(*xDlSy
9670: 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
9680: 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
9690: 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69  r *zSymbol))(voi
96a0: 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  d);.  void (*xDl
96b0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
96c0: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
96d0: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
96e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
96f0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
9700: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
9710: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
9720: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
9730: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
9740: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
9750: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
9760: 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ble*);.  int (*x
9770: 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
9780: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
9790: 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e   char *);.  /* N
97a0: 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
97b0: 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67   appended in fig
97c0: 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
97d0: 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
97e0: 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
97f0: 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
9800: 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a  his happens. */.
9810: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
9820: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
9830: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
9840: 74 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48  thod {H11190} <H
9850: 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31  11140>.**.** {H1
9860: 31 31 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65  1191} These inte
9870: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
9880: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
9890: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
98a0: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
98b0: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
98c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
98d0: 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65  ject. {END}  The
98e0: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
98f0: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
9900: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
9910: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
9920: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 7b 48  oking for..** {H
9930: 31 31 31 39 32 7d 20 57 69 74 68 20 53 51 4c 49  11192} With SQLI
9940: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
9950: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
9960: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
9970: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
9980: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
9990: 2a 20 7b 48 31 31 31 39 33 7d 20 57 69 74 68 20  * {H11193} With 
99a0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
99b0: 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
99c0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
99d0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
99e0: 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72  e file is both r
99f0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
9a00: 61 62 6c 65 2e 0a 2a 2a 20 7b 48 31 31 31 39 34  able..** {H11194
9a10: 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  } With SQLITE_AC
9a20: 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
9a30: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
9a40: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
9a50: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
9a60: 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  able..*/.#define
9a70: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
9a80: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
9a90: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
9aa0: 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65  _READWRITE 1.#de
9ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
9ac0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a  SS_READ      2..
9ad0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9ae0: 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53  Initialize The S
9af0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48  QLite Library {H
9b00: 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30 3e 3c  10130} <S20000><
9b10: 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30100>.**.** Th
9b20: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9b30: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
9b40: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
9b50: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
9b60: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
9b70: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
9b80: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
9b90: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
9ba0: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
9bb0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
9bc0: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a  itialize()..**.*
9bd0: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
9be0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9bf0: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
9c00: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
9c10: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69  .** the first ti
9c20: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
9c30: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
9c40: 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ed during the li
9c50: 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65  fetime of.** the
9c60: 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
9c70: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  it is the first 
9c80: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
9c90: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
9ca0: 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  oked.** followin
9cb0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  g a call to sqli
9cc0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
9cd0: 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69   Only an effecti
9ce0: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
9cf0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9d00: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
9d10: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
9d20: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
9d30: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
9d40: 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  ops..**.** Among
9d50: 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73   other things, s
9d60: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9d70: 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65  e() shall invoke
9d80: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
9d90: 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c  nit().  Similarl
9da0: 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y, sqlite3_shutd
9db0: 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69  own().** shall i
9dc0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73  nvoke sqlite3_os
9dd0: 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  _end()..**.** Th
9de0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9df0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
9e00: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
9e10: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
9e20: 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65  * If for some re
9e30: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
9e40: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
9e50: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
9e60: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
9e70: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
9e80: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
9e90: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
9ea0: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
9eb0: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
9ec0: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
9ed0: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
9ee0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
9ef0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
9f00: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
9f10: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
9f20: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
9f30: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
9f40: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
9f50: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
9f60: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
9f70: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
9f80: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
9f90: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
9fa0: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
9fb0: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
9fc0: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
9fd0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9fe0: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
9ff0: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
a000: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
a010: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
a020: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
a030: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
a040: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
a050: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
a060: 65 61 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20  eady.  However, 
a070: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
a080: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
a090: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
a0a0: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
a0b0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
a0c0: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
a0d0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
a0e0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
a0f0: 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
a100: 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
a110: 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
a120: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a130: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
a140: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
a150: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
a160: 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
a170: 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
a180: 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
a190: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
a1a0: 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
a1b0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
a1c0: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
a1d0: 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
a1e0: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
a1f0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
a200: 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
a210: 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
a220: 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
a230: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
a240: 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
a250: 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
a260: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
a270: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
a280: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
a290: 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
a2a0: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
a2b0: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
a2c0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
a2d0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
a2e0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
a2f0: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
a300: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
a310: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
a320: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
a330: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
a340: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
a350: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
a360: 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
a370: 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
a380: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
a390: 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
a3a0: 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
a3b0: 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
a3c0: 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
a3d0: 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
a3e0: 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
a3f0: 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
a400: 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
a410: 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
a420: 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
a430: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
a440: 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
a450: 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
a460: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
a470: 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
a480: 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
a490: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
a4a0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
a4b0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
a4c0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
a4d0: 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
a4e0: 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
a4f0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
a500: 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
a510: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
a520: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
a530: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a540: 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
a550: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
a560: 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
a570: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
a580: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
a590: 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
a5a0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
a5b0: 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
a5c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
a5d0: 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
a5e0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
a5f0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
a600: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
a610: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
a620: 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
a630: 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
a640: 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75 6e 69  compiled for uni
a650: 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72 20 6f  x, windows, or o
a660: 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62 75 69  s/2..** When bui
a670: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
a680: 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20 74 68  tforms (using th
a690: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
a6a0: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
a6b0: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
a6c0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
a6d0: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
a6e0: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
a6f0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
a700: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
a710: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a720: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
a730: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
a740: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
a750: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a760: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
a770: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
a780: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
a790: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
a7a0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
a7b0: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
a7c0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
a7d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a7e0: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
a7f0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a800: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
a810: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
a820: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
a830: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
a840: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
a850: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
a860: 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 34  ite Library {H14
a870: 31 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33  100} <S20000><S3
a880: 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0200>.** EXPERIM
a890: 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ENTAL.**.** The 
a8a0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a8b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
a8c0: 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
a8d0: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
a8e0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
a8f0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
a900: 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
a910: 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
a920: 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
a930: 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
a940: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
a950: 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
a960: 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
a970: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
a980: 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
a990: 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
a9a0: 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
a9b0: 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
a9c0: 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
a9d0: 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
a9e0: 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
a9f0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
aa00: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
aa10: 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
aa20: 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
aa30: 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
aa40: 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
aa50: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
aa60: 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
aa70: 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
aa80: 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
aa90: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
aaa0: 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
aab0: 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
aac0: 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
aad0: 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
aae0: 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
aaf0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
ab00: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
ab10: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
ab20: 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
ab30: 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
ab40: 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f  utdown()]..** No
ab50: 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
ab60: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
ab70: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
ab80: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
ab90: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
aba0: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
abb0: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
abc0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
abd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
abe0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
abf0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
ac00: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
ac10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
ac20: 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e  NGLETHREAD | con
ac30: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ac40: 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
ac50: 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
ac60: 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
ac70: 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
ac80: 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
ac90: 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
aca0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
acb0: 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
acc0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
acd0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ace0: 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
acf0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
ad00: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e  **.** When a con
ad10: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ad20: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
ad30: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
ad40: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
ad50: 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  ** If the option
ad60: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
ad70: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
ad80: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
ad90: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
ada0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
adb0: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
adc0: 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e   code]..**.** IN
add0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
ade0: 7b 48 31 34 31 30 33 7d 20 41 20 73 75 63 63 65  {H14103} A succe
adf0: 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
ae00: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   of [sqlite3_con
ae10: 66 69 67 28 29 5d 20 73 68 61 6c 6c 20 72 65 74  fig()] shall ret
ae20: 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
ae30: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
ae40: 2a 2a 20 7b 48 31 34 31 30 36 7d 20 54 68 65 20  ** {H14106} The 
ae50: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ae60: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
ae70: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
ae80: 45 5f 4d 49 53 55 53 45 5d 0a 2a 2a 20 20 20 20  E_MISUSE].**    
ae90: 20 20 20 20 20 20 69 66 20 69 74 20 69 73 20 69        if it is i
aea0: 6e 76 6f 6b 65 64 20 69 6e 20 62 65 74 77 65 65  nvoked in betwee
aeb0: 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
aec0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
aed0: 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
aee0: 20 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64    [sqlite3_shutd
aef0: 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  own()]..**.** {H
af00: 31 34 31 32 30 7d 20 41 20 73 75 63 63 65 73 73  14120} A success
af10: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
af20: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
af30: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
af40: 4c 45 54 48 52 45 41 44 5d 29 0a 2a 2a 20 20 20  LETHREAD]).**   
af50: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65 74         shall set
af60: 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68   the default [th
af70: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
af80: 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 0a   Single-thread..
af90: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 33 7d 20 41  **.** {H14123} A
afa0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
afb0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
afc0: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
afd0: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
afe0: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ).**          sh
aff0: 61 6c 6c 20 73 65 74 20 74 68 65 20 64 65 66 61  all set the defa
b000: 75 6c 74 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ult [threading m
b010: 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
b020: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  read..**.** {H14
b030: 31 32 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  126} A successfu
b040: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
b050: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b060: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
b070: 49 5a 45 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20  IZED]).**       
b080: 20 20 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65     shall set the
b090: 20 64 65 66 61 75 6c 74 20 5b 74 68 72 65 61 64   default [thread
b0a0: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
b0b0: 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  ialized..**.** {
b0c0: 48 31 34 31 32 39 7d 20 41 20 73 75 63 63 65 73  H14129} A succes
b0d0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
b0e0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
b0f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
b100: 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 20 20  EX],X).**       
b110: 20 20 20 77 68 65 72 65 20 58 20 69 73 20 61 20     where X is a 
b120: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
b130: 69 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c 69 74  itialized [sqlit
b140: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
b150: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  ].**          ob
b160: 6a 65 63 74 20 73 68 61 6c 6c 20 63 61 75 73 65  ject shall cause
b170: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
b180: 6d 75 74 65 78 20 6f 70 65 72 61 74 69 6f 6e 73  mutex operations
b190: 20 70 65 72 66 6f 72 6d 65 64 0a 2a 2a 20 20 20   performed.**   
b1a0: 20 20 20 20 20 20 20 62 79 20 53 51 4c 69 74 65         by SQLite
b1b0: 20 74 6f 20 75 73 65 20 74 68 65 20 6d 75 74 65   to use the mute
b1c0: 78 20 6d 65 74 68 6f 64 73 20 74 68 61 74 20 77  x methods that w
b1d0: 65 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20 58  ere present in X
b1e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75 72  .**          dur
b1f0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  ing the call to 
b200: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
b210: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 33  )]..**.** {H1413
b220: 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  2} A successful 
b230: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
b240: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
b250: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
b260: 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  ],X).**         
b270: 20 77 68 65 72 65 20 58 20 69 73 20 61 20 70 6f   where X is a po
b280: 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
b290: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
b2a0: 64 73 5d 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 20  ds] object .**  
b2b0: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 6f 76          shall ov
b2c0: 65 72 77 72 69 74 65 20 74 68 65 20 63 6f 6e 74  erwrite the cont
b2d0: 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ent of [sqlite3_
b2e0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 6f  mutex_methods] o
b2f0: 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 20 20  bject.**        
b300: 20 20 77 69 74 68 20 74 68 65 20 6d 75 74 65 78    with the mutex
b310: 20 6d 65 74 68 6f 64 73 20 63 75 72 72 65 6e 74   methods current
b320: 6c 79 20 69 6e 20 75 73 65 20 62 79 20 53 51 4c  ly in use by SQL
b330: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31  ite..**.** {H141
b340: 33 35 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  35} A successful
b350: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
b360: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
b370: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
b380: 2c 4d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ,M).**          
b390: 77 68 65 72 65 20 4d 20 69 73 20 61 20 70 6f 69  where M is a poi
b3a0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 69 74 69  nter to an initi
b3b0: 61 6c 69 7a 65 64 20 5b 73 71 6c 69 74 65 33 5f  alized [sqlite3_
b3c0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
b3d0: 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20           object 
b3e0: 73 68 61 6c 6c 20 63 61 75 73 65 20 61 6c 6c 20  shall cause all 
b3f0: 73 75 62 73 65 71 75 65 6e 74 20 6d 65 6d 6f 72  subsequent memor
b400: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 70 65  y allocation ope
b410: 72 61 74 69 6f 6e 73 0a 2a 2a 20 20 20 20 20 20  rations.**      
b420: 20 20 20 20 70 65 72 66 6f 72 6d 65 64 20 62 79      performed by
b430: 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 74   SQLite to use t
b440: 68 65 20 6d 65 74 68 6f 64 73 20 74 68 61 74 20  he methods that 
b450: 77 65 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20  were present in 
b460: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20 64  .**          M d
b470: 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 74  uring the call t
b480: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b490: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  g()]..**.** {H14
b4a0: 31 33 38 7d 20 41 20 73 75 63 63 65 73 73 66 75  138} A successfu
b4b0: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
b4c0: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b4d0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
b4e0: 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20 20 20  LOC],M).**      
b4f0: 20 20 20 20 77 68 65 72 65 20 4d 20 69 73 20 61      where M is a
b500: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
b510: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
b520: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 73 68 61 6c  ods] object shal
b530: 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76  l.**          ov
b540: 65 72 77 72 69 74 65 20 74 68 65 20 63 6f 6e 74  erwrite the cont
b550: 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ent of [sqlite3_
b560: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  mem_methods] obj
b570: 65 63 74 20 77 69 74 68 20 0a 2a 2a 20 20 20 20  ect with .**    
b580: 20 20 20 20 20 20 74 68 65 20 6d 65 6d 6f 72 79        the memory
b590: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6d 65 74 68   allocation meth
b5a0: 6f 64 73 20 63 75 72 72 65 6e 74 6c 79 20 69 6e  ods currently in
b5b0: 20 75 73 65 20 62 79 0a 2a 2a 20 20 20 20 20 20   use by.**      
b5c0: 20 20 20 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a      SQLite..**.*
b5d0: 2a 20 7b 48 31 34 31 34 31 7d 20 41 20 73 75 63  * {H14141} A suc
b5e0: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
b5f0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
b600: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
b610: 4d 45 4d 53 54 41 54 55 53 5d 2c 31 29 0a 2a 2a  MEMSTATUS],1).**
b620: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
b630: 65 6e 61 62 6c 65 20 74 68 65 20 6d 65 6d 6f 72  enable the memor
b640: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
b650: 74 75 73 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c  tus collection l
b660: 6f 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  ogic..**.** {H14
b670: 31 34 34 7d 20 41 20 73 75 63 63 65 73 73 66 75  144} A successfu
b680: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
b690: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b6a0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
b6b0: 54 55 53 5d 2c 30 29 0a 2a 2a 20 20 20 20 20 20  TUS],0).**      
b6c0: 20 20 20 20 73 68 61 6c 6c 20 64 69 73 61 62 6c      shall disabl
b6d0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
b6e0: 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63  ocation status c
b6f0: 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 2e  ollection logic.
b700: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 37 7d 20  .**.** {H14147} 
b710: 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
b720: 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63 6f 6c  ation status col
b730: 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 20 73 68  lection logic sh
b740: 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20  all be.**       
b750: 20 20 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65     enabled by de
b760: 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fault..**.** {H1
b770: 34 31 35 30 7d 20 41 20 73 75 63 63 65 73 73 66  4150} A successf
b780: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
b790: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
b7a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
b7b0: 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20  CH],S,Z,N).**   
b7c0: 20 20 20 20 20 20 20 77 68 65 72 65 20 5a 20 61         where Z a
b7d0: 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65 67  nd N are non-neg
b7e0: 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 20 61  ative integers a
b7f0: 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nd .**          
b800: 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  S is a pointer t
b810: 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d 65 6d  o an aligned mem
b820: 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 20 6c  ory buffer not l
b830: 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  ess than.**     
b840: 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73 20 69       Z*N bytes i
b850: 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63 61 75  n size shall cau
b860: 73 65 20 53 20 74 6f 20 62 65 20 75 73 65 64 20  se S to be used 
b870: 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
b880: 20 20 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f     [scratch memo
b890: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f  ry allocator] fo
b8a0: 72 20 61 73 20 6d 61 6e 79 20 61 73 20 4e 20 73  r as many as N s
b8b0: 69 6d 75 6c 61 74 61 6e 65 6f 75 73 0a 2a 2a 20  imulataneous.** 
b8c0: 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74           allocat
b8d0: 69 6f 6e 73 20 65 61 63 68 20 6f 66 20 73 69 7a  ions each of siz
b8e0: 65 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31  e Z..**.** {H141
b8f0: 35 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  53} A successful
b900: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
b910: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
b920: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
b930: 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20  ],S,Z,N).**     
b940: 20 20 20 20 20 77 68 65 72 65 20 53 20 69 73 20       where S is 
b950: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  a NULL pointer s
b960: 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65  hall disable the
b970: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 63  .**          [sc
b980: 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c  ratch memory all
b990: 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ocator]..**.** {
b9a0: 48 31 34 31 35 36 7d 20 41 20 73 75 63 63 65 73  H14156} A succes
b9b0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  sful call to.** 
b9c0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
b9d0: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
b9e0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
b9f0: 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20  HE],S,Z,N).**   
ba00: 20 20 20 20 20 20 20 77 68 65 72 65 20 5a 20 61         where Z a
ba10: 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65 67  nd N are non-neg
ba20: 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 20 61  ative integers a
ba30: 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nd .**          
ba40: 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  S is a pointer t
ba50: 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d 65 6d  o an aligned mem
ba60: 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 20 6c  ory buffer not l
ba70: 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  ess than.**     
ba80: 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73 20 69       Z*N bytes i
ba90: 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63 61 75  n size shall cau
baa0: 73 65 20 53 20 74 6f 20 62 65 20 75 73 65 64 20  se S to be used 
bab0: 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
bac0: 20 20 20 5b 70 61 67 65 63 61 63 68 65 20 6d 65     [pagecache me
bad0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
bae0: 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73 20 4e  for as many as N
baf0: 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73 0a 2a   simulataneous.*
bb00: 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63  *          alloc
bb10: 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66 20 73  ations each of s
bb20: 69 7a 65 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ize Z..**.** {H1
bb30: 34 31 35 39 7d 20 41 20 73 75 63 63 65 73 73 66  4159} A successf
bb40: 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20  ul call to.**   
bb50: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
bb60: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
bb70: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
bb80: 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20  ],S,Z,N).**     
bb90: 20 20 20 20 20 77 68 65 72 65 20 53 20 69 73 20       where S is 
bba0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  a NULL pointer s
bbb0: 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65  hall disable the
bbc0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 61  .**          [pa
bbd0: 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  gecache memory a
bbe0: 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a  llocator]..**.**
bbf0: 20 7b 48 31 34 31 36 32 7d 20 41 20 73 75 63 63   {H14162} A succ
bc00: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
bc10: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
bc20: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
bc30: 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20  EAP],H,Z,N).**  
bc40: 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a 20          where Z 
bc50: 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65  and N are non-ne
bc60: 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 20  gative integers 
bc70: 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  and .**         
bc80: 20 48 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20   H is a pointer 
bc90: 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d 65  to an aligned me
bca0: 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 20  mory buffer not 
bcb0: 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20  less than.**    
bcc0: 20 20 20 20 20 20 5a 20 62 79 74 65 73 20 69 6e        Z bytes in
bcd0: 20 73 69 7a 65 20 73 68 61 6c 6c 20 65 6e 61 62   size shall enab
bce0: 6c 65 20 74 68 65 20 5b 6d 65 6d 73 79 73 35 5d  le the [memsys5]
bcf0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
bd00: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  r.**          an
bd10: 64 20 63 61 75 73 65 20 69 74 20 74 6f 20 75 73  d cause it to us
bd20: 65 20 62 75 66 66 65 72 20 53 20 61 73 20 69 74  e buffer S as it
bd30: 73 20 6d 65 6d 6f 72 79 20 73 6f 75 72 63 65 20  s memory source 
bd40: 61 6e 64 20 74 6f 20 75 73 65 0a 2a 2a 20 20 20  and to use.**   
bd50: 20 20 20 20 20 20 20 61 20 6d 69 6e 69 6d 75 6d         a minimum
bd60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
bd70: 20 6f 66 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   of N..**.** {H1
bd80: 34 31 36 35 7d 20 41 20 73 75 63 63 65 73 73 66  4165} A successf
bd90: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
bda0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
bdb0: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
bdc0: 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20  ,H,Z,N).**      
bdd0: 20 20 20 20 77 68 65 72 65 20 48 20 69 73 20 61      where H is a
bde0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73 68   NULL pointer sh
bdf0: 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65 0a  all disable the.
be00: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 6d 65 6d  **          [mem
be10: 73 79 73 35 5d 20 6d 65 6d 6f 72 79 20 61 6c 6c  sys5] memory all
be20: 6f 63 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ocator..**.** {H
be30: 31 34 31 36 38 7d 20 41 20 73 75 63 63 65 73 73  14168} A success
be40: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
be50: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
be60: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
be70: 41 53 49 44 45 5d 2c 5a 2c 4e 29 0a 2a 2a 20 20  ASIDE],Z,N).**  
be80: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 63 61          shall ca
be90: 75 73 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  use the default 
bea0: 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
beb0: 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
bec0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 20 20  figuration.**   
bed0: 20 20 20 20 20 20 20 66 6f 72 20 6e 65 77 20 5b         for new [
bee0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
bef0: 69 6f 6e 73 5d 20 74 6f 20 62 65 20 4e 20 73 6c  ions] to be N sl
bf00: 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73 20 65  ots of Z bytes e
bf10: 61 63 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ach..*/.SQLITE_E
bf20: 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
bf30: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
bf40: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
bf50: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
bf60: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
bf70: 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 32  nnections  {H142
bf80: 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20  00} <S20000>.** 
bf90: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
bfa0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
bfb0: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
bfc0: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
bfd0: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
bfe0: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
bff0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
c000: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
c010: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
c020: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
c030: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
c040: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
c050: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
c060: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
c070: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
c080: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
c090: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
c0a0: 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  ).  The.** sqlit
c0b0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
c0c0: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c  nterface can onl
c0d0: 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69  y be used immedi
c0e0: 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74  ately after.** t
c0f0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
c100: 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  ection is create
c110: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c120: 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _open()],.** [sq
c130: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
c140: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
c150: 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a  n_v2()].  .**.**
c160: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
c170: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c180: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
c190: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  .)  is the.** co
c1a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
c1b0: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
c1c0: 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  de that indicate
c1d0: 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74  s what.** aspect
c1e0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
c1f0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
c200: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
c210: 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63  d..** The only c
c220: 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76  hoice for this v
c230: 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  alue is [SQLITE_
c240: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
c250: 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62  DE]..** New verb
c260: 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
c270: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
c280: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
c290: 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69  QLite..** Additi
c2a0: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64  onal arguments d
c2b0: 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72  epend on the ver
c2c0: 62 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  b..**.** INVARIA
c2d0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32  NTS:.**.** {H142
c2e0: 30 33 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  03} A call to [s
c2f0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c300: 28 44 2c 56 2c 2e 2e 2e 29 5d 20 73 68 61 6c 6c  (D,V,...)] shall
c310: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
c320: 4f 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  OK].**          
c330: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
c340: 68 65 20 63 61 6c 6c 20 69 73 20 73 75 63 63 65  he call is succe
c350: 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ssful..**.** {H1
c360: 34 32 30 36 7d 20 49 66 20 6f 6e 65 20 6f 72 20  4206} If one or 
c370: 6d 6f 72 65 20 73 6c 6f 74 73 20 6f 66 20 74 68  more slots of th
c380: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  e [lookaside mem
c390: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66  ory allocator] f
c3a0: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
c3b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c3c0: 69 6f 6e 5d 20 44 20 61 72 65 20 69 6e 20 75 73  ion] D are in us
c3d0: 65 2c 20 74 68 65 6e 20 61 20 63 61 6c 6c 20 74  e, then a call t
c3e0: 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
c3f0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c400: 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ](D,[SQLITE_DBCO
c410: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
c420: 2e 2e 2e 29 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  ...) shall.**   
c430: 20 20 20 20 20 20 20 66 61 69 6c 20 77 69 74 68         fail with
c440: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59   an [SQLITE_BUSY
c450: 5d 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0a 2a  ] return code..*
c460: 2a 0a 2a 2a 20 7b 48 31 34 32 30 39 7d 20 41 20  *.** {H14209} A 
c470: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
c480: 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  to .**          
c490: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
c4a0: 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42  ig](D,[SQLITE_DB
c4b0: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
c4c0: 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a  ],B,Z,N) where.*
c4d0: 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73 20  *          D is 
c4e0: 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  an open [databas
c4f0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
c500: 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 70 6f  d Z and N are po
c510: 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  sitive.**       
c520: 20 20 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20     integers and 
c530: 42 20 69 73 20 61 6e 20 61 6c 69 67 6e 65 64 20  B is an aligned 
c540: 62 75 66 66 65 72 20 61 74 20 6c 65 61 73 74 20  buffer at least 
c550: 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  Z*N bytes in siz
c560: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  e.**          sh
c570: 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 5b 6c  all cause the [l
c580: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
c590: 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44  allocator] for D
c5a0: 20 74 6f 20 75 73 65 20 62 75 66 66 65 72 20 42   to use buffer B
c5b0: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69   .**          wi
c5c0: 74 68 20 4e 20 73 6c 6f 74 73 20 6f 66 20 5a 20  th N slots of Z 
c5d0: 62 79 74 65 73 20 65 61 63 68 2e 0a 2a 2a 0a 2a  bytes each..**.*
c5e0: 2a 20 7b 48 31 34 32 31 32 7d 20 41 20 73 75 63  * {H14212} A suc
c5f0: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
c600: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
c610: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 5d  lite3_db_config]
c620: 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  (D,[SQLITE_DBCON
c630: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42  FIG_LOOKASIDE],B
c640: 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a 2a 20 20  ,Z,N) where.**  
c650: 20 20 20 20 20 20 20 20 44 20 69 73 20 61 6e 20          D is an 
c660: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
c670: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5a  onnection] and Z
c680: 20 61 6e 64 20 4e 20 61 72 65 20 70 6f 73 69 74   and N are posit
c690: 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
c6a0: 69 6e 74 65 67 65 72 73 20 61 6e 64 20 42 20 69  integers and B i
c6b0: 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  s NULL pointer s
c6c0: 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 0a 2a  hall cause the.*
c6d0: 2a 20 20 20 20 20 20 20 20 20 20 5b 6c 6f 6f 6b  *          [look
c6e0: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
c6f0: 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44 20 74 6f  ocator] for D to
c700: 20 61 20 6f 62 74 61 69 6e 20 5a 2a 4e 20 62 79   a obtain Z*N by
c710: 74 65 20 62 75 66 66 65 72 0a 2a 2a 20 20 20 20  te buffer.**    
c720: 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 70        from the p
c730: 72 69 6d 61 72 79 20 6d 65 6d 6f 72 79 20 61 6c  rimary memory al
c740: 6c 6f 63 61 74 6f 72 20 61 6e 64 20 75 73 65 20  locator and use 
c750: 74 68 61 74 20 62 75 66 66 65 72 0a 2a 2a 20 20  that buffer.**  
c760: 20 20 20 20 20 20 20 20 77 69 74 68 20 4e 20 6c          with N l
c770: 6f 6f 6b 61 73 69 64 65 20 73 6c 6f 74 73 20 6f  ookaside slots o
c780: 66 20 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a  f Z bytes each..
c790: 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31 35 7d 20 41  **.** {H14215} A
c7a0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
c7b0: 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   to .**         
c7c0: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
c7d0: 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44  fig](D,[SQLITE_D
c7e0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
c7f0: 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a  E],B,Z,N) where.
c800: 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73  **          D is
c810: 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61   an open [databa
c820: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
c830: 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 7a  nd Z and N are z
c840: 65 72 6f 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20  ero shall.**    
c850: 20 20 20 20 20 20 64 69 73 61 62 6c 65 20 74 68        disable th
c860: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  e [lookaside mem
c870: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66  ory allocator] f
c880: 6f 72 20 44 2e 0a 2a 2a 0a 2a 2a 0a 2a 2f 0a 53  or D..**.**.*/.S
c890: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
c8a0: 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  AL int sqlite3_d
c8b0: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
c8c0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
c8d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c8e0: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
c8f0: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31  ion Routines {H1
c900: 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a  0155} <S20120>.*
c910: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
c920: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
c930: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
c940: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
c950: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
c960: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
c970: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
c980: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
c990: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
c9a0: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
c9b0: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
c9c0: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
c9d0: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
c9e0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
c9f0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
ca00: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
ca10: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
ca20: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
ca30: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
ca40: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
ca50: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
ca60: 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74  LLOC].  By creat
ca70: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
ca80: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
ca90: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
caa0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
cab0: 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f  fig()] during co
cac0: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a  nfiguration, an.
cad0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  ** application c
cae0: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
caf0: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
cb00: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
cb10: 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c  ystem.** for SQL
cb20: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
cb30: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
cb40: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
cb50: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
cb60: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
cb70: 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  h a built-in mem
cb80: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
cb90: 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74  at is.** perfect
cba0: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
cbb0: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
cbc0: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
cbd0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
cbe0: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
cbf0: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
cc00: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
cc10: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
cc20: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
cc30: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
cc40: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
cc50: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
cc60: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
cc70: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
cc80: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
cc90: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
cca0: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
ccb0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
ccc0: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
ccd0: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
cce0: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
ccf0: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
cd00: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
cd10: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
cd20: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
cd30: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
cd40: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
cd50: 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64  lloc, xFree, and
cd60: 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64   xRealloc method
cd70: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
cd80: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
cd90: 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65  , free(), and re
cda0: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e  alloc() function
cdb0: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
cdc0: 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ard library..**.
cdd0: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
cde0: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
cdf0: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
ce00: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ce10: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
ce20: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
ce30: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
ce40: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
ce50: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
ce60: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
ce70: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
ce80: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
ce90: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
cea0: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
ceb0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
cec0: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
ced0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
cee0: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
cef0: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
cf00: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
cf10: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
cf20: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
cf30: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
cf40: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
cf50: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
cf60: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
cf70: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
cf80: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
cf90: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
cfa0: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
cfb0: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a   power of 2..**.
cfc0: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
cfd0: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
cfe0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
cff0: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
d000: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
d010: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
d020: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
d030: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
d040: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
d050: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
d060: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
d070: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
d080: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
d090: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
d0a0: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
d0b0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
d0c0: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
d0d0: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
d0e0: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
d0f0: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
d100: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
d110: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
d120: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79  xShutdown..*/.ty
d130: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
d140: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d150: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
d160: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
d170: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d180: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
d190: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
d1a0: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
d1b0: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
d1c0: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
d1d0: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
d1e0: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
d1f0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
d200: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
d210: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
d220: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
d230: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
d240: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
d250: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
d260: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
d270: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
d280: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
d290: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
d2a0: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
d2b0: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
d2c0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
d2d0: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
d2e0: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
d2f0: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
d300: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
d310: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
d320: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
d330: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
d340: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
d350: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
d360: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
d370: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
d380: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
d390: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
d3a0: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
d3b0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
d3c0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
d3d0: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31  tion Options {H1
d3e0: 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0160} <S20000>.*
d3f0: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
d400: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
d410: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
d420: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
d430: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d440: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
d450: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
d460: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
d470: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
d480: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
d490: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
d4a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d4b0: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
d4c0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
d4d0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
d4e0: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
d4f0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d500: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
d510: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
d520: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
d530: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
d540: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
d550: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d560: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
d570: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
d580: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
d590: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
d5a0: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
d5b0: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
d5c0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
d5d0: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
d5e0: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
d5f0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d600: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
d610: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
d620: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d630: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
d640: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
d650: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
d660: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
d670: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e  on.  This option
d680: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
d690: 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
d6a0: 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
d6b0: 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
d6c0: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
d6d0: 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
d6e0: 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  hread.</dd>.**.*
d6f0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d700: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
d710: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
d720: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
d730: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
d740: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
d750: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
d760: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
d770: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
d780: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
d790: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
d7a0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
d7b0: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
d7c0: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
d7d0: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
d7e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d7f0: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
d800: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
d810: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
d820: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
d830: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
d840: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
d850: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
d860: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
d870: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
d880: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
d890: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
d8a0: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
d8b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d8c0: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
d8d0: 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65 20 5b  time.  See the [
d8e0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 0a  threading mode].
d8f0: 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  ** documentation
d900: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
d910: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64  information.</dd
d920: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d930: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
d940: 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
d950: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
d960: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
d970: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
d980: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
d990: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
d9a0: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
d9b0: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
d9c0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
d9d0: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
d9e0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
d9f0: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
da00: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
da10: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
da20: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
da30: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
da40: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
da50: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
da60: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
da70: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
da80: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
da90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
daa0: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
dab0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
dac0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
dad0: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
dae0: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
daf0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
db00: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
db10: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
db20: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
db30: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
db40: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
db50: 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  ..** See the [th
db60: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
db70: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
db80: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
db90: 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  mation.</dd>.**.
dba0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
dbb0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
dbc0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
dbd0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
dbe0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
dbf0: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
dc00: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
dc10: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
dc20: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
dc30: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
dc40: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
dc50: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
dc60: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
dc70: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
dc80: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
dc90: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
dca0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
dcb0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
dcc0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
dcd0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
dce0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
dcf0: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
dd00: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
dd10: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
dd20: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
dd30: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
dd40: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
dd50: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
dd60: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
dd70: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
dd80: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
dd90: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
dda0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
ddb0: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
ddc0: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
ddd0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
dde0: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
ddf0: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
de00: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
de10: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
de20: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
de30: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
de40: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
de50: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
de60: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
de70: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
de80: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
de90: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
dea0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
deb0: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
dec0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
ded0: 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
dee0: 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
def0: 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
df00: 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
df10: 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
df20: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
df30: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
df40: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
df50: 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 57  ** statistics. W
df60: 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68  hen disabled, th
df70: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
df80: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
df90: 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65  come .** non-ope
dfa0: 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
dfb0: 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
dfc0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
dfd0: 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
dfe0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
dff0: 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
e000: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
e010: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
e020: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
e030: 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
e040: 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f  **   </ul>.** </
e050: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
e060: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
e070: 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
e080: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
e090: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
e0a0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
e0b0: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
e0c0: 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
e0d0: 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
e0e0: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
e0f0: 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74  ts:  A pointer t
e100: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68  o the memory, th
e110: 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
e120: 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  h scratch buffer
e130: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
e140: 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72 73  umber of buffers
e150: 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a   (N).  The sz.**
e160: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
e170: 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  e a multiple of 
e180: 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61 6d  16. The sz param
e190: 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61  eter should be a
e1a0: 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c 61   few bytes.** la
e1b0: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61 63  rger than the ac
e1c0: 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70 61  tual scratch spa
e1d0: 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65 20  ce required due 
e1e0: 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61  internal overhea
e1f0: 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 0a  d..** The first.
e200: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
e210: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
e220: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
e230: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
e240: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   of memory..** S
e250: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
e260: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  o more than one 
e270: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 61  scratch buffer a
e280: 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61  t once per threa
e290: 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  d, so.** N shoul
e2a0: 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20  d be set to the 
e2b0: 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
e2c0: 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
e2d0: 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70  ds.  The sz.** p
e2e0: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
e2f0: 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20 73  be 6 times the s
e300: 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
e310: 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
e320: 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63   size..** Scratc
e330: 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75 73  h buffers are us
e340: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
e350: 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20  e btree balance 
e360: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a  operation.  If.*
e370: 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c 61  * The btree bala
e380: 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69 74  ncer needs addit
e390: 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79  ional memory bey
e3a0: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
e3b0: 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74  ided by.** scrat
e3c0: 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69 66  ch buffers or if
e3d0: 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66 66   no scratch buff
e3e0: 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65 63  er space is spec
e3f0: 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69  ified, then SQLi
e400: 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73  te.** goes to [s
e410: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
e420: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
e430: 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c  emory it needs.<
e440: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e450: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
e460: 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
e470: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
e480: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
e490: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
e4a0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
e4b0: 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64  use for.** the d
e4c0: 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
e4d0: 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
e4e0: 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ult page cache i
e4f0: 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a  mplemenation.  .
e500: 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
e510: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
e520: 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
e530: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
e540: 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
e550: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
e560: 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
e570: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
e580: 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a  _PCACHE option..
e590: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
e5a0: 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
e5b0: 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70  this option: A p
e5c0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
e5d0: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
e5e0: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
e5f0: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
e600: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
e610: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
e620: 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  sz argument must
e630: 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74   be a power of t
e640: 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
e650: 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 20 66  nd 32768.  The f
e660: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
e670: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
e680: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
e690: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
e6a0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
e6b0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
e6c0: 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
e6d0: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
e6e0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
e6f0: 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
e700: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
e710: 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
e720: 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
e730: 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 64  to cache.  If ad
e740: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
e750: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
e760: 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
e770: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
e780: 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
e790: 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
e7a0: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
e7b0: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
e7c0: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
e7d0: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
e7e0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
e7f0: 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20  n might use one 
e800: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e  or more of the N
e810: 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64   buffers to hold
e820: 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f   .** memory acco
e830: 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69  unting informati
e840: 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  on. </dd>.**.** 
e850: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
e860: 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
e870: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
e880: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
e890: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
e8a0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
e8b0: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
e8c0: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
e8d0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e8e0: 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
e8f0: 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
e900: 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
e910: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
e920: 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
e930: 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
e940: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
e950: 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f   arguments: A po
e960: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
e970: 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ory, the number 
e980: 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
e990: 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
e9a0: 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
e9b0: 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
e9c0: 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66 69  e.  If.** the fi
e9d0: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
e9e0: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
e9f0: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
ea00: 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
ea10: 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
ea20: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
ea30: 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
ea40: 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
ea50: 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
ea60: 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
ea70: 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
ea80: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
ea90: 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a  ALLOC].  If the.
eaa0: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
eab0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
eac0: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
ead0: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
eae0: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
eaf0: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
eb00: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
eb10: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
eb20: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
eb30: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
eb40: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
eb50: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
eb60: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
eb70: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
eb80: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
eb90: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
eba0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
ebb0: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
ebc0: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
ebd0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
ebe0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
ebf0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
ec00: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
ec10: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
ec20: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
ec30: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
ec40: 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
ec50: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
ec60: 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
ec70: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
ec80: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
ec90: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
eca0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
ecb0: 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
ecc0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
ecd0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
ece0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
ecf0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
ed00: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
ed10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
ed20: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
ed30: 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
ed40: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
ed50: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
ed60: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
ed70: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
ed80: 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
ed90: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20  utines..** This 
eda0: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
edb0: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
edc0: 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
edd0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
ede0: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
edf0: 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
ee00: 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
ee10: 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
ee20: 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
ee30: 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
ee40: 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ample.</dd>.**.*
ee50: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
ee60: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
ee70: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
ee80: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
ee90: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
eea0: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66  etermine the def
eeb0: 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  ault.** memory a
eec0: 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69  llcation lookasi
eed0: 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e  de optimization.
eee0: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
eef0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
ef00: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
ef10: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
ef20: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
ef30: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
ef40: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
ef50: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
ef60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ef70: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ef80: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
ef90: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
efa0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
efb0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
efc0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
efd0: 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61   pointer to.** a
efe0: 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
eff0: 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
f000: 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
f010: 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
f020: 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
f030: 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
f040: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
f050: 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  .  SQLite makes 
f060: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
f070: 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73   object and uses
f080: 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63   it for page cac
f090: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
f0a0: 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  tions.</dd>.**.*
f0b0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
f0c0: 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64  FIG_GETPCACHE</d
f0d0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
f0e0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
f0f0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
f100: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
f110: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
f120: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
f130: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  s] object.  SQLi
f140: 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65  te copies of the
f150: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65   current.** page
f160: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
f170: 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
f180: 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
f190: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
f1a0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
f1b0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
f1c0: 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
f1d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
f1e0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
f1f0: 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
f200: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f210: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
f220: 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
f230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f240: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
f250: 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
f260: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
f270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f280: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
f290: 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
f2a0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
f2b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f2c0: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
f2d0: 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
f2e0: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
f2f0: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
f300: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
f310: 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
f320: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
f330: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
f340: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
f350: 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
f360: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
f370: 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
f380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f390: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
f3a0: 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
f3b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f3c0: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
f3d0: 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
f3e0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
f3f0: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
f400: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
f410: 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
f420: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
f430: 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
f440: 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
f450: 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
f460: 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
f470: 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
f480: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f490: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
f4a0: 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
f4b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f4c0: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
f4d0: 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c        14  /* sql
f4e0: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
f4f0: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
f500: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
f510: 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f  TPCACHE    15  /
f520: 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
f530: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a  _methods* */../*
f540: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
f550: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
f560: 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c 53 32  ons {H10170} <S2
f570: 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0000>.** EXPERIM
f580: 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ENTAL.**.** Thes
f590: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
f5a0: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
f5b0: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
f5c0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
f5d0: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
f5e0: 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
f5f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
f600: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
f610: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
f620: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
f630: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
f640: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
f650: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
f660: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
f670: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
f680: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
f690: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
f6a0: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
f6b0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
f6c0: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
f6d0: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
f6e0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
f6f0: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
f700: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
f710: 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
f720: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
f730: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
f740: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
f750: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
f760: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
f770: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
f780: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f790: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
f7a0: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
f7b0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
f7c0: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
f7d0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
f7e0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
f7f0: 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
f800: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
f810: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
f820: 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
f830: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
f840: 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
f850: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
f860: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
f870: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f880: 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
f890: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
f8a0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
f8b0: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
f8c0: 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
f8d0: 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
f8e0: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 20  kaside memory.  
f8f0: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
f900: 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c  ument may be NUL
f910: 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
f920: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
f930: 63 61 74 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  cate the lookasi
f940: 64 65 0a 2a 2a 20 62 75 66 66 65 72 20 69 74 73  de.** buffer its
f950: 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
f960: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54  e3_malloc()].  T
f970: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
f980: 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
f990: 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
f9a0: 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
f9b0: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 61 72  and the third ar
f9c0: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
f9d0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
f9e0: 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
f9f0: 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
fa00: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
fa10: 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
fa20: 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
fa30: 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
fa40: 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
fa50: 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
fa60: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  s.</dd>.**.** </
fa70: 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
fa80: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
fa90: 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31  OOKASIDE    1001
faa0: 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
fab0: 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt */.../*.** CA
fac0: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
fad0: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
fae0: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
faf0: 7b 48 31 32 32 30 30 7d 20 3c 53 31 30 37 30 30  {H12200} <S10700
fb00: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
fb10: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
fb20: 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
fb30: 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
fb40: 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
fb50: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
fb60: 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
fb70: 66 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78  f SQLite. The ex
fb80: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
fb90: 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
fba0: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
fbb0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
fbc0: 6d 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73  mpatibility cons
fbd0: 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  iderations..**.*
fbe0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
fbf0: 0a 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45 61 63  .** {H12201} Eac
fc00: 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20  h new [database 
fc10: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c  connection] shal
fc20: 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20 20  l have the.**   
fc30: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
fc40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
fc50: 65 61 74 75 72 65 20 64 69 73 61 62 6c 65 64 20  eature disabled 
fc60: 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
fc70: 2a 20 7b 48 31 32 32 30 32 7d 20 54 68 65 20 5b  * {H12202} The [
fc80: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
fc90: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c  _result_codes(D,
fca0: 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  F)] interface sh
fcb0: 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20  all enable.**   
fcc0: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
fcd0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
fce0: 6f 72 20 74 68 65 20 20 5b 64 61 74 61 62 61 73  or the  [databas
fcf0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
fd00: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74  **          if t
fd10: 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 20 69  he F parameter i
fd20: 73 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62  s true, or disab
fd30: 6c 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20  le them if F is 
fd40: 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  false..*/.int sq
fd50: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
fd60: 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
fd70: 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
fd80: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fd90: 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
fda0: 6f 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c 53  owid {H12220} <S
fdb0: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63  10700>.**.** Eac
fdc0: 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
fdd0: 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
fde0: 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
fdf0: 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
fe00: 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
fe10: 22 72 6f 77 69 64 22 2e 20 54 68 65 20 72 6f 77  "rowid". The row
fe20: 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
fe30: 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
fe40: 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
fe50: 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
fe60: 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
fe70: 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
fe80: 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
fe90: 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
fea0: 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
feb0: 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a  d columns. If.**
fec0: 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
fed0: 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
fee0: 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
fef0: 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f  KEY then that co
ff00: 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
ff10: 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
ff20: 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68   rowid..**.** Th
ff30: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
ff40: 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  ns the rowid of 
ff50: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
ff60: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
ff70: 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20  NSERT] into the 
ff80: 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
ff90: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
ffa0: 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
ffb0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ffc0: 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73  .  If no success
ffd0: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
ffe0: 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
fff0: 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
10000 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
10010 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
10020 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 5b  d..**.** If an [
10030 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
10040 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
10050 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20   then the rowid 
10060 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
10070 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e  ** row is return
10080 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
10090 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ne as long as th
100a0 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e  e trigger is run
100b0 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
100c0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65  e the trigger te
100d0 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61  rminates, the va
100e0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
100f0 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
10100 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c  reverts to the l
10110 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74  ast value insert
10120 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  ed before the tr
10130 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a  igger fired..**.
10140 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  ** An [INSERT] t
10150 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
10160 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
10170 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
10180 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
10190 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
101a0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
101b0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
101c0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
101d0 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20  e.  Thus INSERT 
101e0 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
101f0 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
10200 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
10210 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
10220 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
10230 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
10240 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
10250 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
10260 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
10270 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49  n fails.  When I
10280 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
10290 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
102a0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
102b0 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
102c0 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
102d0 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
102e0 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
102f0 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
10300 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
10310 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
10320 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
10330 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
10340 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
10350 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
10360 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
10370 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46  terface..**.** F
10380 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
10390 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
103a0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
103b0 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
103c0 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
103d0 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
103e0 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
103f0 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   back..**.** INV
10400 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
10410 48 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c  H12221} The [sql
10420 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
10430 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69  _rowid()] functi
10440 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  on shall return 
10450 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 20 20 20  the rowid.**    
10460 20 20 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73        of the mos
10470 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
10480 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 70 65 72  ful [INSERT] per
10490 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61  formed on the sa
104a0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  me.**          [
104b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
104c0 69 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20  ion] and within 
104d0 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68  the same or high
104e0 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20  er level.**     
104f0 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e       trigger con
10500 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66  text, or zero if
10510 20 74 68 65 72 65 20 68 61 76 65 20 62 65 65 6e   there have been
10520 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 0a 2a   no qualifying.*
10530 2a 20 20 20 20 20 20 20 20 20 20 5b 49 4e 53 45  *          [INSE
10540 52 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  RT] statements..
10550 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20 54  **.** {H12223} T
10560 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
10570 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
10580 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
10590 72 65 74 75 72 6e 20 74 68 65 0a 2a 2a 20 20 20  return the.**   
105a0 20 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75         same valu
105b0 65 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  e when called fr
105c0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  om the same trig
105d0 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20  ger context.**  
105e0 20 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74          immediat
105f0 65 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61  ely before and a
10600 66 74 65 72 20 61 20 5b 52 4f 4c 4c 42 41 43 4b  fter a [ROLLBACK
10610 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  ]..**.** ASSUMPT
10620 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
10630 32 33 32 7d 20 49 66 20 61 20 73 65 70 61 72 61  232} If a separa
10640 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
10650 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
10660 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
10670 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61            databa
10680 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
10690 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
106a0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
106b0 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  id()].**        
106c0 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75    function is ru
106d0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
106e0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
106f0 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a  insert rowid,.**
10700 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
10710 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
10720 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
10730 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
10740 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
10750 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20    unpredictable 
10760 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
10770 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
10780 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
10790 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20 69            last i
107a0 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a  nsert rowid..*/.
107b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
107c0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
107d0 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
107e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
107f0 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
10800 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
10810 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c  ified {H12240} <
10820 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10600>.**.** Th
10830 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
10840 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
10850 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
10860 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
10870 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
10880 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
10890 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
108a0 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
108b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
108c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
108d0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
108e0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
108f0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e  parameter..** On
10900 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ly changes that 
10910 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
10920 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49  cified by the [I
10930 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
10940 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ,.** or [DELETE]
10950 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
10960 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
10970 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
10980 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
10990 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
109a0 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74  . Use the [sqlit
109b0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
109c0 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ()] function.** 
109d0 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
109e0 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
109f0 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  ges including ch
10a00 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
10a10 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  triggers..**.** 
10a20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
10a30 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
10a40 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
10a50 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
10a60 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
10a70 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
10a80 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
10a90 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
10aa0 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
10ab0 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 52  ide effects of R
10ac0 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
10ad0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a  t resolution,.**
10ae0 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54   rollback, ABORT
10af0 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f   processing, DRO
10b00 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61  P TABLE, or by a
10b10 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68  ny other.** mech
10b20 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f  anisms do not co
10b30 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f  unt as direct ro
10b40 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a  w changes..**.**
10b50 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
10b60 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
10b70 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
10b80 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
10b90 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
10ba0 72 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 65  ript of a trigge
10bb0 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  r.  Most SQL sta
10bc0 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
10bd0 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
10be0 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
10bf0 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
10c00 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
10c10 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
10c20 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
10c30 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
10c40 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
10c50 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
10c60 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
10c70 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
10c80 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
10c90 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
10ca0 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
10cb0 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
10cc0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  ation..**.** Cal
10cd0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
10ce0 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
10cf0 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
10d00 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
10d10 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
10d20 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
10d30 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
10d40 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
10d50 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
10d60 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
10d70 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
10d80 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
10d90 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
10da0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
10db0 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
10dc0 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
10dd0 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c   Thus, when call
10de0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
10df0 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
10e00 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
10e10 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
10e20 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
10e30 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
10e40 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
10e50 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
10e60 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
10e70 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74 68  top level.  With
10e80 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
10e90 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
10ea0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
10eb0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
10ec0 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
10ed0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
10ee0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
10ef0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
10f00 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
10f10 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
10f20 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
10f30 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
10f40 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
10f50 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
10f60 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
10f70 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
10f80 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
10f90 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
10fa0 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
10fb0 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
10fc0 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  own context..**.
10fd0 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
10fe0 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64  ents the command
10ff0 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
11000 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57  ble" without a W
11010 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62  HERE clause.** b
11020 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72  y dropping and r
11030 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61  ecreating the ta
11040 62 6c 65 2e 20 20 44 6f 69 6e 67 20 73 6f 20 69  ble.  Doing so i
11050 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68  s much faster th
11060 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f  an going.** thro
11070 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67  ugh and deleting
11080 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d   individual elem
11090 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61  ents from the ta
110a0 62 6c 65 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ble.  Because of
110b0 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a   this.** optimiz
110c0 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74  ation, the delet
110d0 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20  ions in "DELETE 
110e0 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20  FROM table" are 
110f0 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  not row changes 
11100 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  and.** will not 
11110 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68  be counted by th
11120 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
11130 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  s() or [sqlite3_
11140 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
11150 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72  .** functions, r
11160 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
11170 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
11180 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
11190 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74  iginally.** in t
111a0 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65  he table.  To ge
111b0 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
111c0 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
111d0 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65  r of rows delete
111e0 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54  d, use.** "DELET
111f0 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45  E FROM table WHE
11200 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 20 20  RE 1" instead.  
11210 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69  Or recompile usi
11220 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
11230 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f  E_OMIT_TRUNCATE_
11240 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f  OPTIMIZATION] co
11250 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11260 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65  n to disable the
11270 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  .** optimization
11280 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e   on all queries.
11290 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
112a0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 31  S:.**.** {H12241
112b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
112c0 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
112d0 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  on shall return 
112e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
112f0 20 20 20 20 20 20 20 20 20 20 72 6f 77 20 63 68            row ch
11300 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
11310 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
11320 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a  INSERT, UPDATE,.
11330 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 44  **          or D
11340 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
11350 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
11360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
11370 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
11380 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
11390 6f 72 20 68 69 67 68 65 72 20 74 72 69 67 67 65  or higher trigge
113a0 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65  r context, or ze
113b0 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65  ro if there have
113c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74  .**          not
113d0 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 66   been any qualif
113e0 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 73  ying row changes
113f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 33 7d  ..**.** {H12243}
11400 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74   Statements of t
11410 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20  he form "DELETE 
11420 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20  FROM tablename" 
11430 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20  with no.**      
11440 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65      WHERE clause
11450 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73 75 62   shall cause sub
11460 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
11470 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
11480 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
11490 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f 2c   to return zero,
114a0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
114b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
114c0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6f 72  umber of rows or
114d0 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 20  iginally in the 
114e0 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53 53  table..**.** ASS
114f0 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
11500 7b 41 31 32 32 35 32 7d 20 49 66 20 61 20 73 65  {A12252} If a se
11510 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
11520 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
11530 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
11540 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
11550 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73          while [s
11560 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
11570 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
11580 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
11590 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
115a0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
115b0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
115c0 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
115d0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
115e0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
115f0 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
11600 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
11610 64 69 66 69 65 64 20 7b 48 31 32 32 36 30 7d 20  dified {H12260} 
11620 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10600>.**.** T
11630 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
11640 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
11650 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
11660 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c  aused by INSERT,
11670 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20 44 45  .** UPDATE or DE
11680 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
11690 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62  since the [datab
116a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
116b0 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54  was opened..** T
116c0 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65  he count include
116d0 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72  s all changes fr
116e0 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 20 63  om all trigger c
116f0 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65 76 65  ontexts.  Howeve
11700 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20  r,.** the count 
11710 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
11720 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f   changes used to
11730 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41   implement REPLA
11740 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a  CE constraints,.
11750 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20  ** do rollbacks 
11760 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  or ABORT process
11770 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74 61 62  ing, or DROP tab
11780 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a  le processing..*
11790 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20 61 72  * The changes ar
117a0 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f  e counted as soo
117b0 6e 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  n as the stateme
117c0 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
117d0 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  em is.** complet
117e0 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ed (when the sta
117f0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73  tement handle is
11800 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
11810 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
11820 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
11830 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20  lize()])..**.** 
11840 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
11850 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44  s the command "D
11860 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
11870 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52  " without a WHER
11880 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64  E clause.** by d
11890 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72  ropping and recr
118a0 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65  eating the table
118b0 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68  .  (This is much
118c0 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69   faster than goi
118d0 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e  ng.** through an
118e0 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76  d deleting indiv
118f0 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66  idual elements f
11900 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20  rom the table.) 
11910 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73   Because of this
11920 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  .** optimization
11930 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20  , the deletions 
11940 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  in "DELETE FROM 
11950 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72  table" are not r
11960 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a  ow changes and.*
11970 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f  * will not be co
11980 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  unted by the sql
11990 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f  ite3_changes() o
119a0 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  r [sqlite3_total
119b0 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66  _changes()].** f
119c0 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64  unctions, regard
119d0 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62  less of the numb
119e0 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74  er of elements t
119f0 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61  hat were origina
11a00 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61  lly.** in the ta
11a10 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20  ble.  To get an 
11a20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f  accurate count o
11a30 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
11a40 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
11a50 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
11a60 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
11a70 20 69 6e 73 74 65 61 64 2e 20 20 20 4f 72 20 72   instead.   Or r
11a80 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67 20 74  ecompile using t
11a90 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d  he.** [SQLITE_OM
11aa0 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50 54 49  IT_TRUNCATE_OPTI
11ab0 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70 69 6c  MIZATION] compil
11ac0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 6f  e-time option to
11ad0 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20   disable the.** 
11ae0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f 6e 20  optimization on 
11af0 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  all queries..**.
11b00 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
11b10 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
11b20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
11b30 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
11b40 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 31 7d 20  .**.** {H12261} 
11b50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  The [sqlite3_tot
11b60 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65  al_changes()] re
11b70 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20  turns the total 
11b80 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20  number.**       
11b90 20 20 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65     of row change
11ba0 73 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45  s caused by INSE
11bb0 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f  RT, UPDATE, and/
11bc0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20  or DELETE.**    
11bd0 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73        statements
11be0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
11bf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11c00 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20  n], in any.**   
11c10 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63         trigger c
11c20 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68  ontext, since th
11c30 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
11c40 63 74 69 6f 6e 20 77 61 73 20 63 72 65 61 74 65  ction was create
11c50 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 33  d..**.** {H12263
11c60 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  } Statements of 
11c70 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45  the form "DELETE
11c80 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22   FROM tablename"
11c90 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20   with no.**     
11ca0 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73       WHERE claus
11cb0 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e  e shall not chan
11cc0 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
11cd0 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
11ce0 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f    by [sqlite3_to
11cf0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a  tal_changes()]..
11d00 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
11d10 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 36 34  S:.**.** {A12264
11d20 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  } If a separate 
11d30 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
11d40 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
11d50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11d60 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
11d70 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
11d80 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
11d90 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
11da0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20   the value.**   
11db0 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20         returned 
11dc0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
11dd0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
11de0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
11df0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
11e00 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
11e10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
11e20 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
11e30 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31  unning Query {H1
11e40 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a  2270} <S30500>.*
11e50 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
11e60 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
11e70 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
11e80 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
11e90 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
11ea0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
11eb0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
11ec0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
11ed0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
11ee0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
11ef0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
11f00 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
11f10 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
11f20 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
11f30 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
11f40 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
11f50 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
11f60 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  diately..**.** I
11f70 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
11f80 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
11f90 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
11fa0 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
11fb0 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
11fc0 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
11fd0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
11fe0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
11ff0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
12000 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
12010 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
12020 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12030 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
12040 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
12050 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
12060 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
12070 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
12080 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
12090 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
120a0 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
120b0 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
120c0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
120d0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
120e0 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
120f0 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
12100 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
12110 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
12120 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
12130 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
12140 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  * An SQL operati
12150 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
12160 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
12170 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
12180 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  RUPT]..** If the
12190 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
121a0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
121b0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
121c0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
121d0 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
121e0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
121f0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
12200 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
12210 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
12220 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
12230 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20  ically..**.** A 
12240 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
12250 69 6e 74 65 72 72 75 70 74 28 29 20 68 61 73 20  interrupt() has 
12260 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
12270 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
12280 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
12290 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e  after sqlite3_in
122a0 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
122b0 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
122c0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  NTS:.**.** {H122
122d0 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  71} The [sqlite3
122e0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e  _interrupt()] in
122f0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72  terface will for
12300 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a  ce all running.*
12310 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73  *          SQL s
12320 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
12330 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ated with the sa
12340 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
12350 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
12360 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72     to halt after
12370 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d   processing at m
12380 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e  ost one addition
12390 61 6c 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  al row of data..
123a0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 32 7d 20 41  **.** {H12272} A
123b0 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
123c0 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
123d0 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  pted by [sqlite3
123e0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
123f0 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72            will r
12400 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
12410 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20  TERRUPT]..**.** 
12420 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
12430 2a 2a 20 7b 41 31 32 32 37 39 7d 20 49 66 20 74  ** {A12279} If t
12440 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
12450 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
12460 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
12470 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20  errupt()].**    
12480 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67        is running
12490 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
124a0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
124b0 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  pen..*/.void sql
124c0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
124d0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
124e0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
124f0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
12500 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
12510 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20 3c 53  lete {H10510} <S
12520 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  70200>.**.** The
12530 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
12540 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61  useful for comma
12550 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
12560 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
12570 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
12580 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
12590 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65  s to form comple
125a0 74 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65  te a SQL stateme
125b0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
125c0 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
125d0 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
125e0 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
125f0 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
12600 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73  r parsing.  Thes
12610 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
12620 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 69 6e  n true if the in
12630 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
12640 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
12650 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
12660 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65  ment.  A stateme
12670 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
12680 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
12690 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
126a0 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
126b0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72   and is not a fr
126c0 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43  agment of a.** C
126d0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
126e0 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f  atement.  Semico
126f0 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
12700 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
12710 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
12720 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
12730 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
12740 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
12750 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
12760 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
12770 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
12780 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
12790 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
127a0 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
127b0 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
127c0 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
127d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
127e0 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
127f0 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
12800 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
12810 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
12820 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
12830 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
12840 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
12850 0a 2a 2a 20 7b 48 31 30 35 31 31 7d 20 41 20 73  .** {H10511} A s
12860 75 63 63 65 73 73 66 75 6c 20 65 76 61 6c 75 61  uccessful evalua
12870 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
12880 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 0a  _complete()] or.
12890 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
128a0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
128b0 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20 73 68 61  )] functions sha
128c0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ll.**          r
128d0 65 74 75 72 6e 20 61 20 6e 75 6d 65 72 69 63 20  eturn a numeric 
128e0 31 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  1 if and only if
128f0 20 74 68 65 20 6c 61 73 74 20 6e 6f 6e 2d 77 68   the last non-wh
12900 69 74 65 73 70 61 63 65 0a 2a 2a 20 20 20 20 20  itespace.**     
12910 20 20 20 20 20 74 6f 6b 65 6e 20 69 6e 20 74 68       token in th
12920 65 69 72 20 69 6e 70 75 74 20 69 73 20 61 20 73  eir input is a s
12930 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 20 69 73  emicolon that is
12940 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 0a   not in between.
12950 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
12960 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66  BEGIN and END of
12970 20 61 20 43 52 45 41 54 45 20 54 52 49 47 47 45   a CREATE TRIGGE
12980 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  R statement..**.
12990 2a 2a 20 7b 48 31 30 35 31 32 7d 20 49 66 20 61  ** {H10512} If a
129a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
129b0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
129c0 64 75 72 69 6e 67 20 61 6e 20 69 6e 76 6f 63 61  during an invoca
129d0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
129e0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   of [sqlite3_com
129f0 70 6c 65 74 65 28 29 5d 20 6f 72 20 5b 73 71 6c  plete()] or [sql
12a00 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
12a10 29 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20  )] then the.**  
12a20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20          routine 
12a30 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51  shall return [SQ
12a40 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
12a50 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
12a60 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 32 7d 20 54  **.** {A10512} T
12a70 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
12a80 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
12a90 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
12aa0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
12ab0 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
12ac0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35  ing..**.** {A105
12ad0 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f  13} The input to
12ae0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
12af0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
12b00 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
12b10 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54  d.**          UT
12b20 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
12b30 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
12b40 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
12b50 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
12b60 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
12b70 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
12b80 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
12b90 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
12ba0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
12bb0 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
12bc0 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
12bd0 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30 7d 20  Errors {H12310} 
12be0 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S40400>.**.** T
12bf0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
12c00 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
12c10 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
12c20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
12c30 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
12c40 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
12c50 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
12c60 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  le that another 
12c70 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
12c80 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
12c90 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 75  .**.** If the bu
12ca0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
12cb0 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
12cc0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
12cd0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
12ce0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
12cf0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
12d00 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
12d10 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20  he lock. If the 
12d20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
12d30 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
12d40 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
12d50 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
12d60 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
12d70 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ts..**.** The fi
12d80 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
12d90 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61  the handler is a
12da0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
12db0 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
12dc0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
12dd0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
12de0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
12df0 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  r().  The second
12e00 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
12e10 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  the handler call
12e20 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
12e30 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
12e40 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
12e50 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
12e60 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
12e70 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 49  ocking event.  I
12e80 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
12e90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
12ea0 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
12eb0 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
12ec0 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
12ed0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
12ee0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
12ef0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
12f00 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
12f10 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20  returned..** If 
12f20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
12f30 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
12f40 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
12f50 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
12f60 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
12f70 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
12f80 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
12f90 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
12fa0 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
12fb0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
12fc0 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
12fd0 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
12fe0 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
12ff0 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
13000 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69  tention. If SQLi
13010 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
13020 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
13030 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
13040 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
13050 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
13060 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
13070 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
13080 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
13090 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
130a0 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  D] instead of in
130b0 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20  voking the busy 
130c0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
130d0 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
130e0 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
130f0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
13100 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
13110 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
13120 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
13130 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
13140 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
13150 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
13160 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
13170 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
13180 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
13190 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
131a0 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
131b0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
131c0 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
131d0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
131e0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
131f0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
13200 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
13210 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
13220 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
13230 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
13240 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
13250 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
13260 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
13270 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
13280 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
13290 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
132a0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
132b0 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
132c0 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
132d0 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
132e0 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
132f0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
13300 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
13310 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
13320 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
13330 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
13340 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  eed..**.** The d
13350 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
13360 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
13370 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
13380 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
13390 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
133a0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
133b0 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  D].** when SQLit
133c0 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
133d0 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
133e0 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
133f0 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
13400 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
13410 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
13420 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
13430 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
13440 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
13450 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
13460 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
13470 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
13480 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
13490 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
134a0 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
134b0 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
134c0 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
134d0 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
134e0 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
134f0 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
13500 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c    If it is unabl
13510 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65  e to promote the
13520 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20   lock, then the 
13530 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63  in-memory.** cac
13540 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20  he will be left 
13550 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65  in an inconsiste
13560 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20  nt state and so 
13570 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
13580 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72  e is promoted fr
13590 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c  om the relativel
135a0 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45  y benign [SQLITE
135b0 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65  _BUSY] to.** the
135c0 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51   more severe [SQ
135d0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
135e0 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72  ED].  This error
135f0 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
13600 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
13610 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
13620 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
13630 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
13640 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
13650 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
13660 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
13670 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
13680 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
13690 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
136a0 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
136b0 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
136c0 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
136d0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20  **.** There can 
136e0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
136f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
13700 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
13710 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
13720 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
13730 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
13740 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
13750 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
13760 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65  t handler.  Note
13770 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
13780 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
13790 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
137a0 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
137b0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
137c0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
137d0 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
137e0 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
137f0 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
13800 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
13810 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
13820 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
13830 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41  busy handler.  A
13840 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
13850 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
13860 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
13870 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  .** .** INVARIAN
13880 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31  TS:.**.** {H1231
13890 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
138a0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 43  busy_handler(D,C
138b0 2c 41 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  ,A)] function sh
138c0 61 6c 6c 20 72 65 70 6c 61 63 65 0a 2a 2a 20 20  all replace.**  
138d0 20 20 20 20 20 20 20 20 62 75 73 79 20 63 61 6c          busy cal
138e0 6c 62 61 63 6b 20 69 6e 20 74 68 65 20 5b 64 61  lback in the [da
138f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13900 6e 5d 20 44 20 77 69 74 68 20 61 20 6e 65 77 0a  n] D with a new.
13910 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 6e 65  **          a ne
13920 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 43  w busy handler C
13930 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e   and application
13940 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 41 2e   data pointer A.
13950 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 32 7d 20  .**.** {H12312} 
13960 4e 65 77 6c 79 20 63 72 65 61 74 65 64 20 5b 64  Newly created [d
13970 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13980 6f 6e 73 5d 20 73 68 61 6c 6c 20 68 61 76 65 20  ons] shall have 
13990 61 20 62 75 73 79 0a 2a 2a 20 20 20 20 20 20 20  a busy.**       
139a0 20 20 20 68 61 6e 64 6c 65 72 20 6f 66 20 4e 55     handler of NU
139b0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31  LL..**.** {H1231
139c0 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d  4} When two or m
139d0 6f 72 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ore [database co
139e0 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61 72 65  nnections] share
139f0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b   a.**          [
13a00 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
13a10 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20 63 6f  hared_cache | co
13a20 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20  mmon cache],.** 
13a30 20 20 20 20 20 20 20 20 20 74 68 65 20 62 75 73           the bus
13a40 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68  y handler for th
13a50 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
13a60 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20  ction currently 
13a70 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
13a80 20 20 74 68 65 20 63 61 63 68 65 20 73 68 61 6c    the cache shal
13a90 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  l be invoked whe
13aa0 6e 20 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f  n the cache enco
13ab0 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a  unters a lock..*
13ac0 2a 0a 2a 2a 20 7b 48 31 32 33 31 36 7d 20 49 66  *.** {H12316} If
13ad0 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
13ae0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
13af0 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20   zero, then the 
13b00 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
13b10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
13b20 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c  t provoked the l
13b30 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20 73 68 61  ocking event sha
13b40 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
13b50 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_BUSY]..**.** {
13b60 48 31 32 33 31 38 7d 20 53 51 4c 69 74 65 20 73  H12318} SQLite s
13b70 68 61 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65  hall invokes the
13b80 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69   busy handler wi
13b90 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
13ba0 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20   which.**       
13bb0 20 20 20 61 72 65 20 61 20 63 6f 70 79 20 6f 66     are a copy of
13bc0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 73 75 70   the pointer sup
13bd0 70 6c 69 65 64 20 62 79 20 74 68 65 20 33 72 64  plied by the 3rd
13be0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
13bf0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
13c00 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
13c10 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f  )] and a count o
13c20 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
13c30 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  prior.**        
13c40 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66    invocations of
13c50 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
13c60 72 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c  r for the same l
13c70 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a  ocking event..**
13c80 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
13c90 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33 31 39 7d 20  .**.** {A12319} 
13ca0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
13cb0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
13cc0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
13cd0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
13ce0 20 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73    or [prepared s
13cf0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
13d00 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
13d10 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20  handler..*/.int 
13d20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
13d30 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
13d40 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
13d50 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
13d60 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
13d70 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 48   Busy Timeout {H
13d80 31 32 33 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a  12340} <S40410>.
13d90 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
13da0 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
13db0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
13dc0 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
13dd0 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
13de0 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
13df0 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
13e00 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
13e10 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c  cked.  The handl
13e20 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
13e30 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
13e40 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
13e50 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
13e60 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
13e70 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
13e80 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 74 65 72  . {H12343} After
13e90 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
13ea0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
13eb0 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
13ec0 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
13ed0 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
13ee0 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
13ef0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
13f00 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
13f10 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
13f20 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  ** Calling this 
13f30 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
13f40 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
13f50 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
13f60 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
13f70 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
13f80 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  rs..**.** There 
13f90 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
13fa0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
13fb0 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
13fc0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
13fd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20  connection] any 
13fe0 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
13ff0 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
14000 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
14010 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
14020 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
14030 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
14040 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
14050 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
14060 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
14070 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
14080 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
14090 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34  TS:.**.** {H1234
140a0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
140b0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
140c0 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 6f  function shall o
140d0 76 65 72 72 69 64 65 20 61 6e 79 20 70 72 69 6f  verride any prio
140e0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
140f0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
14100 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  out()] or [sqlit
14110 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
14120 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  )] setting.**   
14130 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61         on the sa
14140 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
14150 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  nection]..**.** 
14160 7b 48 31 32 33 34 33 7d 20 49 66 20 74 68 65 20  {H12343} If the 
14170 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
14180 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
14190 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c 65 73  imeout()] is les
141a0 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  s than.**       
141b0 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a     or equal to z
141c0 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 62 75  ero, then the bu
141d0 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c  sy handler shall
141e0 20 62 65 20 63 6c 65 61 72 65 64 20 73 6f 20 74   be cleared so t
141f0 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
14200 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6c  all subsequent l
14210 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20 69 6d  ocking events im
14220 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e  mediately return
14230 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
14240 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 34 7d 20 49  **.** {H12344} I
14250 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
14260 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
14270 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
14280 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a  is a positive.**
14290 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
142a0 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73 79 20   N, then a busy 
142b0 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65  handler shall be
142c0 20 73 65 74 20 74 68 61 74 20 72 65 70 65 61 74   set that repeat
142d0 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20  edly calls.**   
142e0 20 20 20 20 20 20 20 74 68 65 20 78 53 6c 65 65         the xSlee
142f0 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20 74 68  p() method in th
14300 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  e [sqlite3_vfs |
14310 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 5d 20   VFS interface] 
14320 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20  until.**        
14330 20 20 65 69 74 68 65 72 20 74 68 65 20 6c 6f 63    either the loc
14340 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e 74 69  k clears or unti
14350 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69 76 65  l the cumulative
14360 20 73 6c 65 65 70 20 74 69 6d 65 0a 2a 2a 20 20   sleep time.**  
14370 20 20 20 20 20 20 20 20 72 65 70 6f 72 74 65 64          reported
14380 20 62 61 63 6b 20 62 79 20 78 53 6c 65 65 70 28   back by xSleep(
14390 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c  ) exceeds N mill
143a0 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74  iseconds..*/.int
143b0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
143c0 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
143d0 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
143e0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
143f0 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
14400 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
14410 65 73 20 7b 48 31 32 33 37 30 7d 20 3c 53 31 30  es {H12370} <S10
14420 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  000>.**.** Defin
14430 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
14440 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
14450 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
14460 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
14470 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
14480 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
14490 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
144a0 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
144b0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
144c0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
144d0 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
144e0 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
144f0 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
14500 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
14510 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
14520 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
14530 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
14540 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
14550 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
14560 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
14570 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
14580 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
14590 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
145a0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
145b0 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
145c0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
145d0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
145e0 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
145f0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
14600 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
14610 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
14620 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
14630 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
14640 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
14650 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
14660 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
14670 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
14680 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
14690 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
146a0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
146b0 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
146c0 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
146d0 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
146e0 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
146f0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
14700 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
14710 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
14720 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
14730 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
14740 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
14750 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
14760 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
14770 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
14780 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
14790 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
147a0 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
147b0 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
147c0 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
147d0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
147e0 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
147f0 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
14800 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
14810 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
14820 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
14830 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
14840 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
14850 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61  e()]..**.** As a
14860 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
14870 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
14880 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
14890 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
148a0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
148b0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
148c0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
148d0 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
148e0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
148f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14900 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
14910 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
14920 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
14930 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
14940 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
14950 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
14960 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
14970 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
14980 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
14990 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
149a0 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
149b0 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
149c0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
149d0 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
149e0 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
149f0 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
14a00 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
14a10 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
14a20 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
14a30 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
14a40 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
14a50 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
14a60 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
14a70 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
14a80 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
14a90 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
14aa0 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
14ab0 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
14ac0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
14ad0 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
14ae0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14af0 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
14b00 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
14b10 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
14b20 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14b30 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
14b40 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
14b50 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
14b60 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
14b70 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
14b80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
14b90 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
14ba0 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
14bb0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
14bc0 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
14bd0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
14be0 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
14bf0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
14c00 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
14c10 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  nd parameter.  I
14c20 74 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  t returns a resu
14c30 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
14c40 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
14c50 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
14c60 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
14c70 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  er the calling f
14c80 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  unction has fini
14c90 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 72  shed using the r
14ca0 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64  esult, it should
14cb0 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69  .** pass the poi
14cc0 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65 73 75  nter to the resu
14cd0 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69  lt table to sqli
14ce0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14cf0 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
14d00 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
14d10 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
14d20 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
14d30 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
14d40 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14d50 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
14d60 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
14d70 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
14d80 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
14d90 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
14da0 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
14db0 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
14dc0 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
14dd0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
14de0 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
14df0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
14e00 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
14e10 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
14e20 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14e30 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
14e40 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
14e50 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
14e60 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
14e70 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
14e80 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
14e90 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
14ea0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
14eb0 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
14ec0 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
14ed0 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
14ee0 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
14ef0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
14f00 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
14f10 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
14f20 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
14f30 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
14f40 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
14f50 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
14f60 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
14f70 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
14f80 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
14f90 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
14fa0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
14fb0 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  de()] or [sqlite
14fc0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a  3_errmsg()]..**.
14fd0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
14fe0 2a 0a 2a 2a 20 7b 48 31 32 33 37 31 7d 20 49 66  *.** {H12371} If
14ff0 20 61 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f   a [sqlite3_get_
15000 74 61 62 6c 65 28 29 5d 20 66 61 69 6c 73 20 61  table()] fails a
15010 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15020 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  on, then.**     
15030 20 20 20 20 20 69 74 20 73 68 61 6c 6c 20 66 72       it shall fr
15040 65 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  ee the result ta
15050 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72  ble under constr
15060 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 20 74 68  uction, abort th
15070 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75  e.**          qu
15080 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20  ery in process, 
15090 73 6b 69 70 20 61 6e 79 20 73 75 62 73 65 71 75  skip any subsequ
150a0 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65 74  ent queries, set
150b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
150c0 20 2a 70 61 7a 52 65 73 75 6c 74 20 6f 75 74 70   *pazResult outp
150d0 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55  ut pointer to NU
150e0 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  LL and return [S
150f0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
15100 0a 2a 2a 20 7b 48 31 32 33 37 33 7d 20 49 66 20  .** {H12373} If 
15110 74 68 65 20 70 6e 43 6f 6c 75 6d 6e 20 70 61 72  the pnColumn par
15120 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
15130 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
15140 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20  is not NULL.**  
15150 20 20 20 20 20 20 20 20 74 68 65 6e 20 61 20 73          then a s
15160 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
15170 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
15180 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73 68  _get_table()] sh
15190 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
151a0 77 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72  write the number
151b0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
151c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
151d0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65  esult set of the
151e0 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 43   query into *pnC
151f0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  olumn..**.** {H1
15200 32 33 37 34 7d 20 49 66 20 74 68 65 20 70 6e 52  2374} If the pnR
15210 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ow parameter to 
15220 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
15230 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c  le()] is not NUL
15240 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  L.**          th
15250 65 6e 20 61 20 73 75 63 63 65 73 73 66 75 6c 20  en a successful 
15260 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
15270 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
15280 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20  ()] shall.**    
15290 20 20 20 20 20 20 77 72 69 74 65 73 20 74 68 65        writes the
152a0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
152b0 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
152c0 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66     result set of
152d0 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20   the query into 
152e0 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48  *pnRow..**.** {H
152f0 31 32 33 37 36 7d 20 41 20 73 75 63 63 65 73 73  12376} A success
15300 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
15310 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  f [sqlite3_get_t
15320 61 62 6c 65 28 29 5d 20 74 68 61 74 20 63 6f 6d  able()] that com
15330 70 75 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  putes.**        
15340 20 20 4e 20 72 6f 77 73 20 6f 66 20 72 65 73 75    N rows of resu
15350 6c 74 20 77 69 74 68 20 43 20 63 6f 6c 75 6d 6e  lt with C column
15360 73 20 70 65 72 20 72 6f 77 20 73 68 61 6c 6c 20  s per row shall 
15370 6d 61 6b 65 20 2a 70 61 7a 52 65 73 75 6c 74 0a  make *pazResult.
15380 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e  **          poin
15390 74 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  t to an array of
153a0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 28 4e 2b   pointers to (N+
153b0 31 29 2a 43 20 73 74 72 69 6e 67 73 20 77 68 65  1)*C strings whe
153c0 72 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  re the first.** 
153d0 20 20 20 20 20 20 20 20 20 43 20 73 74 72 69 6e           C strin
153e0 67 73 20 61 72 65 20 63 6f 6c 75 6d 6e 20 6e 61  gs are column na
153f0 6d 65 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20  mes as obtained 
15400 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20  from.**         
15410 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
15420 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 74 68 65  _name()] and the
15430 20 72 65 73 74 20 61 72 65 20 63 6f 6c 75 6d 6e   rest are column
15440 20 72 65 73 75 6c 74 20 76 61 6c 75 65 73 0a 2a   result values.*
15450 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69  *          obtai
15460 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
15470 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
15480 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 39 7d  ..**.** {H12379}
15490 20 54 68 65 20 76 61 6c 75 65 73 20 69 6e 20 74   The values in t
154a0 68 65 20 70 61 7a 52 65 73 75 6c 74 20 61 72 72  he pazResult arr
154b0 61 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ay returned by [
154c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
154d0 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  e()].**         
154e0 20 73 68 61 6c 6c 20 72 65 6d 61 69 6e 20 76 61   shall remain va
154f0 6c 69 64 20 75 6e 74 69 6c 20 63 6c 65 61 72 65  lid until cleare
15500 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
15510 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
15520 2a 2a 20 7b 48 31 32 33 38 32 7d 20 57 68 65 6e  ** {H12382} When
15530 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
15540 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69   during evaluati
15550 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67  on of [sqlite3_g
15560 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20  et_table()].**  
15570 20 20 20 20 20 20 20 20 74 68 65 20 66 75 6e 63          the func
15580 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 2a  tion shall set *
15590 70 61 7a 52 65 73 75 6c 74 20 74 6f 20 4e 55 4c  pazResult to NUL
155a0 4c 2c 20 77 72 69 74 65 20 61 6e 20 65 72 72 6f  L, write an erro
155b0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
155c0 20 20 20 20 20 20 69 6e 74 6f 20 6d 65 6d 6f 72        into memor
155d0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
155e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
155f0 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 20 20 20 20  )], make.**     
15600 20 20 20 20 20 2a 2a 70 7a 45 72 72 6d 73 67 20       **pzErrmsg 
15610 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 65 72  point to that er
15620 72 6f 72 20 6d 65 73 73 61 67 65 2c 20 61 6e 64  ror message, and
15630 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 20 20 20   return a.**    
15640 20 20 20 20 20 20 61 70 70 72 6f 70 72 69 61 74        appropriat
15650 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
15660 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
15670 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
15680 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
15690 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
156a0 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
156b0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
156c0 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
156d0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
156e0 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
156f0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
15700 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
15710 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
15720 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
15730 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
15740 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
15750 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
15760 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
15770 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
15780 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
15790 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
157a0 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
157b0 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
157c0 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
157d0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
157e0 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
157f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15800 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
15810 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
15820 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d  nctions {H17400}
15830 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30   <S70000><S20000
15840 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
15850 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61  utines are worka
15860 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
15870 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
15880 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
15890 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
158a0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
158b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70  * The sqlite3_mp
158c0 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
158d0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
158e0 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
158f0 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
15900 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
15910 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
15920 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
15930 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
15940 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
15950 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
15960 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
15970 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
15980 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74  e()].  Both rout
15990 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
159a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
159b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
159c0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
159d0 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
159e0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
159f0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
15a00 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49   string..**.** I
15a10 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  n sqlite3_snprin
15a20 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
15a30 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
15a40 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
15a50 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
15a60 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
15a70 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
15a80 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
15a90 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
15aa0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15ab0 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
15ac0 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
15ad0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15ae0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
15af0 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
15b00 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
15b10 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
15b20 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
15b30 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  .  This is an.**
15b40 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
15b50 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
15b60 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
15b70 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
15b80 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
15b90 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73  ility.  Note als
15ba0 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
15bb0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
15bc0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
15bd0 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
15be0 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
15bf0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
15c00 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
15c10 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
15c20 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20  ffer.  We admit 
15c30 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
15c40 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
15c50 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
15c60 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
15c70 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
15c80 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
15c90 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
15ca0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
15cb0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
15cc0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
15cd0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
15ce0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f  ity..**.** As lo
15cf0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
15d00 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
15d10 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
15d20 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
15d30 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
15d40 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
15d50 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
15d60 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72  inated.  The fir
15d70 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
15d80 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
15d90 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
15da0 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
15db0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
15dc0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
15dd0 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
15de0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
15df0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
15e00 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
15e10 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
15e20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
15e30 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
15e40 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
15e50 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
15e60 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
15e70 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
15e80 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
15e90 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
15ea0 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
15eb0 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
15ec0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
15ed0 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
15ee0 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
15ef0 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64   "%q", "%Q", and
15f00 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
15f10 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69  *.** The %q opti
15f20 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
15f30 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
15f40 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74  titutes a null-t
15f50 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
15f60 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
15f70 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
15f80 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
15f90 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
15fa0 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
15fb0 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
15fc0 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
15fd0 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f   literal.  By do
15fe0 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
15ff0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
16000 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
16010 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
16020 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
16030 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
16040 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
16050 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
16060 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
16070 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
16080 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
16090 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
160a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
160b0 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
160c0 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
160d0 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
160e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
160f0 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
16100 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
16110 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
16120 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
16130 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
16140 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
16150 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
16160 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
16170 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
16180 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
16190 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
161a0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
161b0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
161c0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
161d0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
161e0 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
161f0 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
16200 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
16210 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
16220 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
16230 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
16240 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
16250 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
16260 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
16270 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
16280 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
16290 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
162a0 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
162b0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
162c0 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
162d0 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
162e0 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
162f0 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
16300 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
16310 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
16320 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
16330 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
16340 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
16350 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
16360 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
16370 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
16380 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
16390 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
163a0 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
163b0 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
163c0 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
163d0 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
163e0 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
163f0 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
16400 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
16410 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
16420 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20  l..**.** The %Q 
16430 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
16440 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
16450 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
16460 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
16470 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
16480 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
16490 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
164a0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
164b0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
164c0 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
164d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
164e0 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
164f0 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
16500 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
16510 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20  uotes) in place 
16520 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e  of the %Q option
16530 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  .  So, for examp
16540 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
16550 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
16560 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
16570 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
16580 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
16590 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
165a0 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
165b0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
165c0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
165d0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
165e0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
165f0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
16600 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
16610 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
16620 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
16630 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
16640 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
16650 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
16660 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
16670 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
16680 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
16690 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
166a0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78   option works ex
166b0 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20  actly like "%s" 
166c0 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
166d0 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
166e0 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
166f0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
16700 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
16710 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
16720 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
16730 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
16740 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a  string. {END}.**
16750 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
16760 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 33 7d 20 20  **.** {H17403}  
16770 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  The [sqlite3_mpr
16780 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c  intf()] and [sql
16790 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d  ite3_vmprintf()]
167a0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20   interfaces.**  
167b0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
167c0 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20  either pointers 
167d0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
167e0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
167f0 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20   held in.**     
16800 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74        memory obt
16810 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
16820 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
16830 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69   NULL pointers i
16840 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  f.**           a
16850 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
16860 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c  3_malloc()] fail
16870 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 36  s..**.** {H17406
16880 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
16890 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  snprintf()] inte
168a0 72 66 61 63 65 20 77 72 69 74 65 73 20 61 20 7a  rface writes a z
168b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
168c0 2a 20 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  *           UTF-
168d0 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68  8 string into th
168e0 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64  e buffer pointed
168f0 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
16900 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  d parameter.**  
16910 20 20 20 20 20 20 20 20 20 70 72 6f 76 69 64 65           provide
16920 64 20 74 68 61 74 20 74 68 65 20 66 69 72 73 74  d that the first
16930 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 67 72   parameter is gr
16940 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e  eater than zero.
16950 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 37 7d 20  .**.** {H17407} 
16960 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e   The [sqlite3_sn
16970 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66  printf()] interf
16980 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69  ace does not wri
16990 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20  te slots of.**  
169a0 20 20 20 20 20 20 20 20 20 69 74 73 20 6f 75 74           its out
169b0 70 75 74 20 62 75 66 66 65 72 20 28 74 68 65 20  put buffer (the 
169c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
169d0 29 20 6f 75 74 73 69 64 65 20 74 68 65 20 72 61  ) outside the ra
169e0 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nge.**          
169f0 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d   of 0 through N-
16a00 31 20 28 77 68 65 72 65 20 4e 20 69 73 20 74 68  1 (where N is th
16a10 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
16a20 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  r).**           
16a30 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
16a40 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
16a50 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
16a60 20 20 20 20 72 65 71 75 65 73 74 65 64 20 62 79      requested by
16a70 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63   the format spec
16a80 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68  ification..*/.ch
16a90 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
16aa0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
16ab0 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
16ac0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
16ad0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
16ae0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
16af0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
16b00 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
16b10 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
16b20 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
16b30 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
16b40 73 74 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53  stem {H17300} <S
16b50 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20000>.**.** The
16b60 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73   SQLite core  us
16b70 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
16b80 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
16b90 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
16ba0 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
16bb0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
16bc0 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
16bd0 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
16be0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
16bf0 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
16c00 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
16c10 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
16c20 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
16c30 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
16c40 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
16c50 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
16c60 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
16c70 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c   The sqlite3_mal
16c80 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
16c90 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
16ca0 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
16cb0 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
16cc0 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
16cd0 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
16ce0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
16cf0 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
16d00 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
16d10 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
16d20 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
16d30 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
16d40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
16d50 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
16d60 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
16d70 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
16d80 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
16d90 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
16da0 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
16db0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
16dc0 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c  *.** Calling sql
16dd0 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
16de0 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
16df0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
16e00 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
16e10 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
16e20 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
16e30 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
16e40 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
16e50 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
16e60 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
16e70 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
16e80 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
16e90 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
16ea0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
16eb0 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
16ec0 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
16ed0 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
16ee0 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
16ef0 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
16f00 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
16f10 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
16f20 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
16f30 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
16f40 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
16f50 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
16f60 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
16f70 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
16f80 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
16f90 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
16fa0 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
16fb0 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
16fc0 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
16fd0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
16fe0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
16ff0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
17000 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
17010 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
17020 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
17030 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17040 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
17050 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  loc()..**.** The
17060 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
17070 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
17080 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
17090 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
170a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
170b0 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
170c0 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  tes, where N is 
170d0 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  the.** second pa
170e0 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65  rameter.  The me
170f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
17100 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73  to be resized is
17110 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
17120 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65  rameter.  If the
17130 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
17140 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
17150 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
17160 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
17170 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
17180 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
17190 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
171a0 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
171b0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
171c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
171d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
171e0 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64  ** If the second
171f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
17200 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
17210 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
17220 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
17230 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
17240 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
17250 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
17260 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65  e3_free(P) where
17270 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20   P is the first 
17280 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
17290 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
172a0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ** sqlite3_reall
172b0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
172c0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
172d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
172e0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
172f0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
17300 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
17310 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
17320 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20  vailable..** If 
17330 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
17340 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
17350 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
17360 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
17370 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
17380 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
17390 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
173a0 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
173b0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
173c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
173d0 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
173e0 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
173f0 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
17400 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
17410 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
17420 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
17430 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
17440 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d  d..**.** The mem
17450 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
17460 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17470 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
17480 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
17490 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
174a0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
174b0 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44  e boundary. {END
174c0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  }.**.** The defa
174d0 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ult implementati
174e0 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79  on of the memory
174f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
17500 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68  ystem uses.** th
17510 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  e malloc(), real
17520 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
17530 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
17540 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
17550 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d  ary..** {H17382}
17560 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c   However, if SQL
17570 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
17580 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
17590 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c  TE_MEMORY_SIZE=<
175a0 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70  i>NNN</i> C prep
175b0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 28  rocessor macro (
175c0 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  where <i>NNN</i>
175d0 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65  .** is an intege
175e0 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  r), then SQLite 
175f0 63 72 65 61 74 65 20 61 20 73 74 61 74 69 63 20  create a static 
17600 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73  array of at leas
17610 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  t.** <i>NNN</i> 
17620 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
17630 64 20 75 73 65 73 20 74 68 61 74 20 61 72 72 61  d uses that arra
17640 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  y for all of its
17650 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f   dynamic.** memo
17660 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
17670 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69  eds. {END}  Addi
17680 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  tional memory al
17690 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a  locator options.
176a0 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ** may be added 
176b0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
176c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  es..**.** In SQL
176d0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
176e0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
176f0 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
17700 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
17710 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
17720 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
17730 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
17740 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
17750 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
17760 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
17770 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
17780 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
17790 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
177a0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
177b0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
177c0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
177d0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
177e0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
177f0 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
17800 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
17810 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
17820 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
17830 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
17840 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
17850 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
17860 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
17870 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
17880 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
17890 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
178a0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
178b0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
178c0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
178d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
178e0 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
178f0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
17900 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
17910 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
17920 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
17930 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
17940 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
17950 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  EM]..**.** INVAR
17960 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
17970 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69  7303}  The [sqli
17980 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69  te3_malloc(N)] i
17990 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
179a0 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65   either a pointe
179b0 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
179c0 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63 6b 65    a newly checke
179d0 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 20 61  d-out block of a
179e0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
179f0 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  of memory.**    
17a00 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 38         that is 8
17a10 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f  -byte aligned, o
17a20 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  r it returns NUL
17a30 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 62 6c  L if it is unabl
17a40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  e.**           t
17a50 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20 72 65  o fulfill the re
17a60 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  quest..**.** {H1
17a70 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71 6c 69  7304}  The [sqli
17a80 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69  te3_malloc(N)] i
17a90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
17aa0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
17ab0 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  if.**           
17ac0 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
17ad0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e  r equal to zero.
17ae0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 35 7d 20  .**.** {H17305} 
17af0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 72   The [sqlite3_fr
17b00 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ee(P)] interface
17b10 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79   releases memory
17b20 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20   previously.**  
17b30 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65           returne
17b40 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
17b50 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
17b60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
17b70 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d  ,.**           m
17b80 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c 61 62  aking it availab
17b90 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a  le for reuse..**
17ba0 0a 2a 2a 20 7b 48 31 37 33 30 36 7d 20 20 41 20  .** {H17306}  A 
17bb0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
17bc0 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20  _free(NULL)] is 
17bd0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
17be0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 30 7d  ..**.** {H17310}
17bf0 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
17c00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e  ite3_realloc(0,N
17c10 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  )] is equivalent
17c20 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20   to a call.**   
17c30 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69          to [sqli
17c40 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a  te3_malloc(N)]..
17c50 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 32 7d 20 20  **.** {H17312}  
17c60 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
17c70 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d  e3_realloc(P,0)]
17c80 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
17c90 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  o a call.**     
17ca0 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65        to [sqlite
17cb0 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a  3_free(P)]..**.*
17cc0 2a 20 7b 48 31 37 33 31 35 7d 20 20 54 68 65 20  * {H17315}  The 
17cd0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
17ce0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
17cf0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  ()], [sqlite3_re
17d00 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20  alloc()],.**    
17d10 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71 6c 69         and [sqli
17d20 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20  te3_free()] for 
17d30 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72  all of its memor
17d40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64  y allocation and
17d50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 64 65  .**           de
17d60 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
17d70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 38 7d  ..**.** {H17318}
17d80 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72    The [sqlite3_r
17d90 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74  ealloc(P,N)] int
17da0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
17db0 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 0a  ither a pointer.
17dc0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
17dd0 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b  a block of check
17de0 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66  ed-out memory of
17df0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
17e00 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20  s in size.**    
17e10 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 38         that is 8
17e20 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f  -byte aligned, o
17e30 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
17e40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 31 7d  ..**.** {H17321}
17e50 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    When [sqlite3_
17e60 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65  realloc(P,N)] re
17e70 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  turns a non-NULL
17e80 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72   pointer, it fir
17e90 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  st.**           
17ea0 63 6f 70 69 65 73 20 74 68 65 20 66 69 72 73 74  copies the first
17eb0 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f 6e 74   K bytes of cont
17ec0 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20  ent from P into 
17ed0 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20 20 20  the newly.**    
17ee0 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64         allocated
17ef0 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20 4b 20   block, where K 
17f00 69 73 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66  is the lesser of
17f10 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a 65 20   N and the size 
17f20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  of.**           
17f30 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  the buffer P..**
17f40 0a 2a 2a 20 7b 48 31 37 33 32 32 7d 20 20 57 68  .** {H17322}  Wh
17f50 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
17f60 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
17f70 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
17f80 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a  nter, it first.*
17f90 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 6c 65  *           rele
17fa0 61 73 65 73 20 74 68 65 20 62 75 66 66 65 72 20  ases the buffer 
17fb0 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 33  P..**.** {H17323
17fc0 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
17fd0 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
17fe0 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
17ff0 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a 2a 20   buffer P is.** 
18000 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 6d 6f            not mo
18010 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65 61 73  dified or releas
18020 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  ed..**.** ASSUMP
18030 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
18040 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69 6e 74  7350}  The point
18050 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
18060 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
18070 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
18080 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20 20  alloc()].**     
18090 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 65 69        must be ei
180a0 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
180b0 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
180c0 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
180d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 6e  .**           in
180e0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
180f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
18100 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
18110 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
18120 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74  **           not
18130 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
18140 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35  ed..**.** {A1735
18150 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  1}  The applicat
18160 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
18170 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
18180 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  art of.**       
18190 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d      a block of m
181a0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
181b0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
181c0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
181d0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65      [sqlite3_fre
181e0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
181f0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
18200 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
18210 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
18220 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
18230 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
18240 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
18250 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
18260 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
18270 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
18280 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20 3c 53  tics {H17370} <S
18290 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  30210>.**.** SQL
182a0 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
182b0 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
182c0 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
182d0 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
182e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
182f0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
18300 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
18310 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
18320 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
18330 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
18340 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
18350 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
18360 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  system..**.** IN
18370 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
18380 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b 73 71  {H17371} The [sq
18390 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
183a0 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
183b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
183c0 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20  of bytes.**     
183d0 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79 20 63       of memory c
183e0 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
183f0 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
18400 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
18410 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20 54 68  *.** {H17373} Th
18420 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
18430 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
18440 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
18450 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20 20  he maximum.**   
18460 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
18470 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
18480 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
18490 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
184a0 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61  k.**          wa
184b0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a  s last reset..**
184c0 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54 68 65  .** {H17374} The
184d0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
184e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
184f0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
18500 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
18510 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
18520 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
18530 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
18540 20 20 20 20 20 20 20 20 20 20 61 64 64 65 64 20            added 
18550 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
18560 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
18570 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
18580 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  oc()],.**       
18590 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68     but not overh
185a0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
185b0 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
185c0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
185d0 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69  *          routi
185e0 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
185f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
18600 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  call..**.** {H17
18610 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20  375} The memory 
18620 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
18630 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
18640 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
18650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
18660 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
18670 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
18680 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
18690 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
186a0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
186b0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
186c0 20 74 72 75 65 2e 20 20 54 68 65 20 76 61 6c 75   true.  The valu
186d0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20  e returned.**   
186e0 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74         by [sqlit
186f0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
18700 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
18710 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
18720 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 6f 72  *          prior
18730 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
18740 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
18750 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
18760 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
18770 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
18780 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
18790 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
187a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
187b0 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
187c0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
187d0 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30  r {H17390} <S200
187e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  00>.**.** SQLite
187f0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
18800 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
18810 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
18820 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
18830 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
18840 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20 77   random ROWIDs w
18850 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
18860 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
18870 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
18880 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
18890 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
188a0 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 52 4e   ROWID.  The PRN
188b0 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
188c0 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
188d0 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
188e0 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
188f0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
18900 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
18910 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
18920 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
18930 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
18940 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
18950 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74  *.** A call to t
18960 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
18970 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
18980 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
18990 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68  ffer P..**.** Th
189a0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
189b0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
189c0 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
189d0 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
189e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
189f0 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
18a00 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
18a10 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
18a20 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
18a30 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
18a40 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
18a50 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
18a60 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62  t..** On all sub
18a70 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
18a80 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
18a90 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
18aa0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
18ab0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
18ac0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
18ad0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
18ae0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
18af0 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ethod..**.** INV
18b00 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
18b10 48 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c  H17392} The [sql
18b20 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
18b30 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,P)] interface 
18b40 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f  writes N bytes o
18b50 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69  f.**          hi
18b60 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
18b70 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  o-randomness int
18b80 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76  o buffer P..*/.v
18b90 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
18ba0 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
18bb0 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
18bc0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
18bd0 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
18be0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ion Callbacks {H
18bf0 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a  12500} <S70100>.
18c00 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
18c10 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61  ne registers a a
18c20 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18c30 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
18c40 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
18c50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
18c60 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
18c70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
18c80 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
18c90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
18ca0 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
18cb0 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
18cc0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
18cd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18ce0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
18cf0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
18d00 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
18d10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
18d20 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
18d30 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
18d40 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a  ].  At various.*
18d50 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
18d60 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
18d70 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
18d80 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
18d90 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
18da0 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
18db0 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
18dc0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
18dd0 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
18de0 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
18df0 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68  are allowed.  Th
18e00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18e10 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
18e20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
18e30 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
18e40 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
18e50 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
18e60 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
18e70 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
18e80 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
18e90 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
18ea0 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
18eb0 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
18ec0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
18ed0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
18ee0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
18ef0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
18f00 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68  an error.  If th
18f10 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18f20 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
18f30 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
18f40 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
18f50 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
18f60 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
18f70 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
18f80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18f90 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
18fa0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
18fb0 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
18fc0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
18fd0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
18fe0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
18ff0 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
19000 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
19010 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
19020 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
19030 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
19040 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65  is ok.  When the
19050 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
19060 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
19070 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19080 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
19090 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
190a0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
190b0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
190c0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
190d0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
190e0 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
190f0 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
19100 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20  denied.  If the 
19110 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
19120 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
19130 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
19140 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
19150 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
19160 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
19170 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
19180 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
19190 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
191a0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
191b0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
191c0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
191d0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
191e0 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
191f0 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
19200 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
19210 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
19220 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
19230 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
19240 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
19250 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
19260 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
19270 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
19280 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
19290 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
192a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
192b0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
192c0 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
192d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
192e0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
192f0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
19300 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64  face. The second
19310 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
19320 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
19330 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
19340 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
19350 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
19360 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
19370 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
19380 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
19390 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  . The third thro
193a0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
193b0 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
193c0 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
193d0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
193e0 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
193f0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
19400 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
19410 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
19420 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
19430 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
19440 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
19450 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
19460 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
19470 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
19480 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
19490 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
194a0 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
194b0 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
194c0 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
194d0 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
194e0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
194f0 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
19500 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
19510 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
19520 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
19530 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
19540 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
19550 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
19560 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
19570 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
19580 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
19590 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
195a0 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
195b0 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
195c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
195d0 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
195e0 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
195f0 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
19600 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
19610 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
19620 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
19630 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
19640 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
19650 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
19660 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
19670 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19680 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
19690 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
196a0 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
196b0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
196c0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
196d0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
196e0 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
196f0 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
19700 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
19710 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
19720 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
19730 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
19740 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
19750 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
19760 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
19770 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
19780 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
19790 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
197a0 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
197b0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
197c0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
197d0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
197e0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
197f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19800 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
19810 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
19820 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
19830 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
19840 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
19850 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68  all.  Disable th
19860 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
19870 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
19880 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
19890 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
198a0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
198b0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
198c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
198d0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
198e0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
198f0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
19900 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19910 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
19920 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
19930 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
19940 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
19950 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
19960 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
19970 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
19980 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
19990 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
199a0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
199b0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
199c0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
199d0 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** When [sqlite3
199e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
199f0 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
19a00 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
19a10 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
19a20 6d 69 67 68 74 20 62 65 20 72 65 70 72 65 70 61  might be reprepa
19a30 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
19a40 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
19a50 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
19a60 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
19a70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19a80 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
19a90 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
19aa0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
19ab0 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
19ac0 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
19ad0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
19ae0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  )]..**.** Note t
19af0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
19b00 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
19b10 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
19b20 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
19b30 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
19b40 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
19b50 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
19b60 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
19b70 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
19b80 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
19b90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
19ba0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
19bb0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20  .**.** {H12501} 
19bc0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
19bd0 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e  _authorizer(D,..
19be0 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  .)] interface re
19bf0 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20  gisters a.**    
19c00 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72        authorizer
19c10 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64   callback with d
19c20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19c30 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  on D..**.** {H12
19c40 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69  502} The authori
19c50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
19c60 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
19c70 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
19c80 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20            being 
19c90 70 61 72 73 65 65 64 20 61 6e 64 20 63 6f 6d 70  parseed and comp
19ca0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  iled..**.** {H12
19cb0 35 30 33 7d 20 49 66 20 74 68 65 20 61 75 74 68  503} If the auth
19cc0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
19cd0 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75  returns any valu
19ce0 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20  e other than.** 
19cf0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
19d00 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
19d10 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
19d20 45 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a  E_DENY], then.**
19d30 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 70            the ap
19d40 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65 72 66  plication interf
19d50 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20 63 61  ace call that ca
19d60 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  used.**         
19d70 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
19d80 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20  callback to run 
19d90 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20  shall fail with 
19da0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
19db0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72  SQLITE_ERROR] er
19dc0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20  ror code and an 
19dd0 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
19de0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
19df0 20 7b 48 31 32 35 30 34 7d 20 57 68 65 6e 20 74   {H12504} When t
19e00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19e10 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
19e20 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20  SQLITE_OK], the 
19e30 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20  operation.**    
19e40 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64 20        described 
19e50 69 73 20 70 72 6f 63 65 73 73 65 64 20 6e 6f 72  is processed nor
19e60 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  mally..**.** {H1
19e70 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61  2505} When the a
19e80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19e90 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
19ea0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
19eb0 20 20 20 20 20 20 20 20 20 20 61 70 70 6c 69 63            applic
19ec0 61 74 69 6f 6e 20 69 6e 74 65 72 66 61 63 65 20  ation interface 
19ed0 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64  call that caused
19ee0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
19ef0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19f00 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c  back to run shal
19f10 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20  l fail.**       
19f20 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49     with an [SQLI
19f30 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20  TE_ERROR] error 
19f40 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f  code and an erro
19f50 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
19f60 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67        explaining
19f70 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73 20   that access is 
19f80 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  denied..**.** {H
19f90 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75  12506} If the au
19fa0 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74  thorizer code (t
19fb0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
19fc0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
19fd0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  er.**          c
19fe0 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c  allback) is [SQL
19ff0 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68  ITE_READ] and th
1a000 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1a010 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1a020 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
1a030 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20  E_IGNORE], then 
1a040 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
1a050 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1a060 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  ucted to.**     
1a070 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55       insert a NU
1a080 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
1a090 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1a0a0 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
1a0b0 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
1a0c0 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b    been read if [
1a0d0 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
1a0e0 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  een returned..**
1a0f0 0a 2a 2a 20 7b 48 31 32 35 30 37 7d 20 49 66 20  .** {H12507} If 
1a100 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1a110 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72  ode (the 2nd par
1a120 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1a130 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20  thorizer.**     
1a140 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69       callback) i
1a150 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72  s anything other
1a160 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45   than [SQLITE_RE
1a170 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  AD], then.**    
1a180 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f        a return o
1a190 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  f [SQLITE_IGNORE
1a1a0 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65  ] has the same e
1a1b0 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45  ffect as [SQLITE
1a1c0 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _DENY]..**.** {H
1a1d0 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 74  12510} The first
1a1e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1a1f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1a200 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1a210 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
1a220 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
1a230 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
1a240 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1a250 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  r()] interface..
1a260 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54  **.** {H12511} T
1a270 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a280 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1a290 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1a2a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
1a2b0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
1a2c0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
1a2d0 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72  pecifies the par
1a2e0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a  ticular action.*
1a2f0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62 65  *          to be
1a300 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
1a310 2a 2a 20 7b 48 31 32 35 31 32 7d 20 54 68 65 20  ** {H12512} The 
1a320 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
1a330 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  xth parameters t
1a340 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
1a350 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  re.**          z
1a360 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1a370 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
1a380 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ain.**          
1a390 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
1a3a0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1a3b0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1a3c0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ized..**.** {H12
1a3d0 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  520} Each call t
1a3e0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  o [sqlite3_set_a
1a3f0 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65  uthorizer()] ove
1a400 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20  rrides.**       
1a410 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c     any previousl
1a420 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68  y installed auth
1a430 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orizer..**.** {H
1a440 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75  12521} A NULL au
1a450 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74  thorizer means t
1a460 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61  hat no authoriza
1a470 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
1a480 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1a490 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  oked..**.** {H12
1a4a0 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74  522} The default
1a4b0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e   authorizer is N
1a4c0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
1a4d0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1a4e0 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
1a4f0 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
1a500 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
1a510 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1a520 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1a530 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
1a540 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
1a550 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a560 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
1a570 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30  rn Codes {H12590
1a580 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <H12500>.**.**
1a590 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1a5a0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1a5b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1a5c0 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
1a5d0 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
1a5e0 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
1a5f0 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
1a600 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
1a610 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
1a620 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
1a630 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
1a640 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
1a650 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
1a660 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1a670 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1a680 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
1a690 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
1a6a0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1a6b0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1a6c0 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1a6d0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1a6e0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1a6f0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1a700 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1a710 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1a720 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1a730 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1a740 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1a750 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1a760 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1a770 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32  es {H12550} <H12
1a780 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  500>.**.** The [
1a790 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1a7a0 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1a7b0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1a7c0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1a7d0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1a7e0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1a7f0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1a800 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1a810 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1a820 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a830 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1a840 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1a850 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1a860 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1a870 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1a880 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1a890 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1a8a0 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1a8b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1a8c0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1a8d0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1a8e0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1a8f0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1a900 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1a910 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1a920 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1a930 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1a940 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1a950 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1a960 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1a970 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1a980 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1a990 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1a9a0 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1a9b0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1a9c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1a9d0 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
1a9e0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1a9f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1aa00 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1aa10 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1aa20 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1aa30 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1aa40 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70  able.  The 6th p
1aa50 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1aa60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1aa70 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
1aa80 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
1aa90 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1aaa0 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1aab0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1aac0 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
1aad0 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
1aae0 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
1aaf0 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
1ab00 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
1ab10 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  SQL code..**.** 
1ab20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1ab30 2a 20 7b 48 31 32 35 35 31 7d 20 54 68 65 20 73  * {H12551} The s
1ab40 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1ab50 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  to an.**        
1ab60 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
1ab70 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1ab80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d  orizer callback]
1ab90 20 73 68 61 6c 6c 20 62 65 20 61 6e 20 69 6e 74   shall be an int
1aba0 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eger.**         
1abb0 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1abc0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d  authorizer code]
1abd0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
1abe0 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20  what action.**  
1abf0 20 20 20 20 20 20 20 20 69 73 20 62 65 69 6e 67          is being
1ac00 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
1ac10 2a 2a 20 7b 48 31 32 35 35 32 7d 20 54 68 65 20  ** {H12552} The 
1ac20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
1ac30 6d 65 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a  meters to the.**
1ac40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1ac50 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1ac60 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  r | authorizatio
1ac70 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20  n callback].**  
1ac80 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 62 65          shall be
1ac90 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
1aca0 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
1acb0 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20   which.**       
1acc0 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20     [SQLITE_COPY 
1acd0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  | authorizer cod
1ace0 65 5d 20 69 73 20 75 73 65 64 20 61 73 20 74 68  e] is used as th
1acf0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1ad00 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35  er..**.** {H1255
1ad10 33 7d 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  3} The 5th param
1ad20 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20  eter to the.**  
1ad30 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1ad40 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1ad50 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
1ad60 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20  lback] shall be 
1ad70 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
1ad80 20 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61       of the data
1ad90 62 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22  base (example: "
1ada0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65  main", "temp", e
1adb0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1adc0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35  le..**.** {H1255
1add0 34 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d  4} The 6th param
1ade0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20  eter to the.**  
1adf0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1ae00 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1ae10 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
1ae20 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20  lback] shall be 
1ae30 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
1ae40 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65       of the inne
1ae50 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1ae60 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1ae70 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1ae80 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
1ae90 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
1aea0 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
1aeb0 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
1aec0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
1aed0 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65            top-le
1aee0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
1aef0 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
1af00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1af10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
1af20 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
1af30 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
1af40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1af50 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
1af60 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
1af70 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1af80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1af90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1afa0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
1afb0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
1afc0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1afd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1afe0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1aff0 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
1b000 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
1b010 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1b020 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1b030 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1b040 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
1b050 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
1b060 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1b070 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b080 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1b090 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
1b0a0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
1b0b0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1b0c0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1b0d0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1b0e0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1b0f0 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
1b100 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1b110 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b120 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1b130 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
1b140 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1b150 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1b160 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b170 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1b180 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
1b190 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1b1a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b1b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b1c0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
1b1d0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
1b1e0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b1f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b200 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b210 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
1b220 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
1b230 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1b240 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b250 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b260 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
1b270 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
1b280 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1b290 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b2a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b2b0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
1b2c0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
1b2d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1b2e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b2f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b300 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
1b310 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
1b320 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b330 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b340 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b350 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
1b360 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
1b370 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1b380 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1b390 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b3a0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
1b3b0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
1b3c0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1b3d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b3e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b3f0 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
1b400 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
1b410 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1b420 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1b430 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b440 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
1b450 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
1b460 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1b470 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b480 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
1b490 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
1b4a0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
1b4b0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1b4c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1b4d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
1b4e0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
1b4f0 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
1b500 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
1b510 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
1b520 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
1b530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b540 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
1b550 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1b560 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1b570 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
1b580 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1b590 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
1b5a0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1b5b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b5c0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
1b5d0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
1b5e0 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  2   /* NULL     
1b5f0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1b600 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b610 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
1b620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
1b630 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b640 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1b650 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1b660 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
1b670 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
1b680 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
1b690 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b6a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b6b0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
1b6c0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
1b6d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1b6e0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
1b6f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b700 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
1b710 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
1b720 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1b730 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b740 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b750 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
1b760 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
1b770 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1b780 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b790 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b7a0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
1b7b0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
1b7c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b7d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b7e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b7f0 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
1b800 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
1b810 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b820 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1b830 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b840 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
1b850 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
1b860 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1b870 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1b880 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b890 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
1b8a0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
1b8b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
1b8c0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
1b8d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b8e0 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
1b8f0 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
1b900 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
1b910 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b920 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
1b930 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  iling Functions 
1b940 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30 30  {H12280} <S60400
1b950 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
1b960 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  L.**.** These ro
1b970 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
1b980 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1b990 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
1b9a0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
1b9b0 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
1b9c0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
1b9d0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
1b9e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
1b9f0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1ba00 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1ba10 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
1ba20 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
1ba30 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
1ba40 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1ba50 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
1ba60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1ba70 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  ]..** The callba
1ba80 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46  ck returns a UTF
1ba90 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
1baa0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1bab0 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65  t text.** as the
1bac0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
1bad0 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
1bae0 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63  g.  Additional c
1baf0 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a  allbacks occur.*
1bb00 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
1bb10 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
1bb20 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
1bb30 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
1bb40 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
1bb50 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
1bb60 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
1bb70 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
1bb80 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  r..**.** The cal
1bb90 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1bba0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1bbb0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
1bbc0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
1bbd0 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
1bbe0 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68  nt finishes.  Th
1bbf0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1bc00 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1bc10 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1bc20 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1bc30 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1bc40 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1bc50 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1bc60 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1bc70 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49   to run..**.** I
1bc80 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1bc90 20 7b 48 31 32 32 38 31 7d 20 54 68 65 20 63 61   {H12281} The ca
1bca0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1bcb0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73  registered by [s
1bcc0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
1bcd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
1bce0 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1bcf0 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76            whenev
1bd00 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  er an SQL statem
1bd10 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
1bd20 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a   to execute and.
1bd30 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
1bd40 65 76 65 72 20 61 20 74 72 69 67 67 65 72 20 73  ever a trigger s
1bd50 75 62 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20  ubprogram first 
1bd60 62 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a  begins to run..*
1bd70 2a 0a 2a 2a 20 7b 48 31 32 32 38 32 7d 20 45 61  *.** {H12282} Ea
1bd80 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
1bd90 74 65 33 5f 74 72 61 63 65 28 29 5d 20 73 68 61  te3_trace()] sha
1bda0 6c 6c 20 6f 76 65 72 72 69 64 65 20 74 68 65 20  ll override the 
1bdb0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20  previously.**   
1bdc0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
1bdd0 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  d trace callback
1bde0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d  ..**.** {H12283}
1bdf0 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61   A NULL trace ca
1be00 6c 6c 62 61 63 6b 20 73 68 61 6c 6c 20 64 69 73  llback shall dis
1be10 61 62 6c 65 20 74 72 61 63 69 6e 67 2e 0a 2a 2a  able tracing..**
1be20 0a 2a 2a 20 7b 48 31 32 32 38 34 7d 20 54 68 65  .** {H12284} The
1be30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1be40 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
1be50 6c 62 61 63 6b 20 73 68 61 6c 6c 20 62 65 20 61  lback shall be a
1be60 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20   copy of.**     
1be70 20 20 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72       the pointer
1be80 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 33   which was the 3
1be90 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  rd argument to [
1bea0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
1beb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d  ..**.** {H12285}
1bec0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1bed0 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
1bee0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a  e callback is a.
1bef0 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
1bf00 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1bf10 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  8 string contain
1bf20 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ing the original
1bf30 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20   text.**        
1bf40 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61    of the SQL sta
1bf50 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73  tement as it was
1bf60 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71   passed into [sq
1bf70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1bf80 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
1bf90 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
1bfa0 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d  t, or an SQL com
1bfb0 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20  ment indicating 
1bfc0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  the beginning.**
1bfd0 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 20 74            of a t
1bfe0 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
1bff0 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37  m..**.** {H12287
1c000 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  } The callback f
1c010 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1c020 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
1c030 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76  rofile()] is inv
1c040 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  oked.**         
1c050 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
1c060 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
1c070 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20  .**.** {H12288} 
1c080 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1c090 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69  ter to the profi
1c0a0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  le callback is a
1c0b0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20   copy of.**     
1c0c0 20 20 20 20 20 74 68 65 20 33 72 64 20 70 61 72       the 3rd par
1c0d0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
1c0e0 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a  e3_profile()]..*
1c0f0 2a 0a 2a 2a 20 7b 48 31 32 32 38 39 7d 20 54 68  *.** {H12289} Th
1c100 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1c110 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c  er to the profil
1c120 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a  e callback is a.
1c130 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
1c140 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1c150 38 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f  8 string that co
1c160 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c  ntains the compl
1c170 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20  ete text of.**  
1c180 20 20 20 20 20 20 20 20 74 68 65 20 53 51 4c 20          the SQL 
1c190 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20  statement as it 
1c1a0 77 61 73 20 70 72 6f 63 65 73 73 65 64 20 62 79  was processed by
1c1b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c1c0 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20  e_v2()].**      
1c1d0 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76      or the equiv
1c1e0 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  alent..**.** {H1
1c1f0 32 32 39 30 7d 20 54 68 65 20 74 68 69 72 64 20  2290} The third 
1c200 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1c210 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1c220 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65  k is an estimate
1c230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
1c240 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61  the number of na
1c250 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c  noseconds of wal
1c260 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71  l-clock time req
1c270 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  uired to.**     
1c280 20 20 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c       run the SQL
1c290 20 73 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20   statement from 
1c2a0 73 74 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e  start to finish.
1c2b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
1c2c0 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
1c2d0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
1c2e0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
1c2f0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
1c300 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
1c310 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
1c320 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
1c330 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
1c340 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
1c350 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
1c360 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
1c370 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
1c380 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c390 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
1c3a0 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32  s Callbacks {H12
1c3b0 39 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a  910} <S60400>.**
1c3c0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1c3d0 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61   configures a ca
1c3e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1c3f0 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73  - the.** progres
1c400 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61  s callback - tha
1c410 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72  t is invoked per
1c420 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
1c430 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67   long.** running
1c440 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1c450 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
1c460 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
1c470 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1c480 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65  _table()].  An e
1c490 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
1c4a0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
1c4b0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
1c4c0 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
1c4d0 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
1c4e0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f  **.** If the pro
1c4f0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
1c500 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1c510 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
1c520 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
1c530 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
1c540 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
1c550 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
1c560 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
1c570 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
1c580 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
1c590 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
1c5a0 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
1c5b0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1c5c0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1c5d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1c5e0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1c5f0 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
1c600 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
1c610 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1c620 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1c630 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1c640 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1c650 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1c660 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1c670 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1c680 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1c690 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1c6a0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1c6b0 2a 0a 2a 2a 20 7b 48 31 32 39 31 31 7d 20 54 68  *.** {H12911} Th
1c6c0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1c6d0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1c6e0 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  y sqlite3_progre
1c6f0 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20  ss_handler().** 
1c700 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f           is invo
1c710 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
1c720 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
1c730 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
1c740 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c750 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
1c760 2a 20 7b 48 31 32 39 31 32 7d 20 54 68 65 20 70  * {H12912} The p
1c770 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1c780 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
1c790 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72   for every N vir
1c7a0 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  tual.**         
1c7b0 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73   machine opcodes
1c7c0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1c7d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1c7e0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1c7f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  the [sqlite3_pro
1c800 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d  gress_handler()]
1c810 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67 69 73   call that regis
1c820 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  tered.**        
1c830 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20    the callback. 
1c840 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   If N is less th
1c850 61 6e 20 31 2c 20 73 71 6c 69 74 65 33 5f 70 72  an 1, sqlite3_pr
1c860 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
1c870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 63 74  .**          act
1c880 73 20 61 73 20 69 66 20 61 20 4e 55 4c 4c 20 70  s as if a NULL p
1c890 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1c8a0 68 61 64 20 62 65 65 6e 20 73 70 65 63 69 66 69  had been specifi
1c8b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  ed..**.** {H1291
1c8c0 33 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  3} The progress 
1c8d0 63 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66 20  callback itself 
1c8e0 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  is identified by
1c8f0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 20 20   the third.**   
1c900 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20         argument 
1c910 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  to sqlite3_progr
1c920 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 2e 0a 2a  ess_handler()..*
1c930 2a 0a 2a 2a 20 7b 48 31 32 39 31 34 7d 20 54 68  *.** {H12914} Th
1c940 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
1c950 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f  t to sqlite3_pro
1c960 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 20  gress_handler() 
1c970 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
1c980 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61   void pointer pa
1c990 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67  ssed to the prog
1c9a0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  ress callback.**
1c9b0 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
1c9c0 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74 20  on each time it 
1c9d0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
1c9e0 2a 20 7b 48 31 32 39 31 35 7d 20 49 66 20 61 20  * {H12915} If a 
1c9f0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1ca00 5f 73 74 65 70 28 29 5d 20 72 65 73 75 6c 74 73  _step()] results
1ca10 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 20 4e   in fewer than N
1ca20 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 20 20 20 20   opcodes.**     
1ca30 20 20 20 20 20 62 65 69 6e 67 20 65 78 65 63 75       being execu
1ca40 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ted, then the pr
1ca50 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1ca60 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64  is never invoked
1ca70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 36 7d  ..**.** {H12916}
1ca80 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b   Every call to [
1ca90 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1caa0 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20  _handler()].**  
1cab0 20 20 20 20 20 20 20 20 6f 76 65 72 77 72 69 74          overwrit
1cac0 65 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  es any previousl
1cad0 79 20 72 65 67 69 73 74 65 72 65 64 20 70 72 6f  y registered pro
1cae0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1caf0 2a 0a 2a 2a 20 7b 48 31 32 39 31 37 7d 20 49 66  *.** {H12917} If
1cb00 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1cb10 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
1cb20 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70  s NULL then no p
1cb30 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20 20 20 20  rogress.**      
1cb40 20 20 20 20 68 61 6e 64 6c 65 72 20 69 73 20 69      handler is i
1cb50 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nvoked..**.** {H
1cb60 31 32 39 31 38 7d 20 49 66 20 74 68 65 20 70 72  12918} If the pr
1cb70 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1cb80 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
1cb90 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74   other than 0, t
1cba0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
1cbb0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1cbc0 61 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e  a if [sqlite3_in
1cbd0 74 65 72 72 75 70 74 28 29 5d 20 68 61 64 20 62  terrupt()] had b
1cbe0 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20  een called..**  
1cbf0 20 20 20 20 20 20 20 20 3c 53 33 30 35 30 30 3e          <S30500>
1cc00 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1cc10 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1cc20 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
1cc30 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
1cc40 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1cc50 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
1cc60 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
1cc70 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37  Connection {H127
1cc80 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a  00} <S40200>.**.
1cc90 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1cca0 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
1ccb0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
1ccc0 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76  hose name is giv
1ccd0 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c  en by the.** fil
1cce0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
1ccf0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
1cd00 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
1cd10 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
1cd20 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1cd30 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1cd40 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
1cd50 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1cd60 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
1cd70 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
1cd80 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b 64 61 74  open16(). A [dat
1cd90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cda0 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
1cdb0 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
1cdc0 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
1cdd0 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
1cde0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
1cdf0 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
1ce00 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
1ce10 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1ce20 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
1ce30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
1ce40 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
1ce50 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
1ce60 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
1ce70 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
1ce80 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1ce90 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20  ].** object. If 
1cea0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
1ceb0 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
1cec0 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
1ced0 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
1cee0 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
1cef0 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
1cf00 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
1cf10 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
1cf20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1cf30 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1cf40 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1cf50 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1cf60 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1cf70 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1cf80 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1cf90 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1cfa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ..**.** The defa
1cfb0 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
1cfc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
1cfd0 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
1cfe0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1cff0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1d000 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
1d010 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
1d020 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1d030 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65   order if sqlite
1d040 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73  3_open16() is us
1d050 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
1d060 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
1d070 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
1d080 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
1d090 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
1d0a0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
1d0b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d0c0 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
1d0d0 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
1d0e0 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
1d0f0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
1d100 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
1d110 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
1d120 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1d130 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
1d140 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
1d150 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
1d160 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
1d170 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
1d180 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
1d190 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
1d1a0 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
1d1b0 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
1d1c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d1d0 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61 72  .  The flags par
1d1e0 61 6d 65 74 65 72 20 63 61 6e 20 74 61 6b 65 20  ameter can take 
1d1f0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
1d200 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
1d210 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
1d220 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
1d230 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
1d240 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20  PEN_NOMUTEX] or 
1d250 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1d260 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 3a 0a 2a  LMUTEX] flags:.*
1d270 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
1d280 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1d290 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
1d2a0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1d2b0 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
1d2c0 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
1d2d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
1d2e0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
1d2f0 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
1d300 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1d310 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b  /dd>.**.** <dt>[
1d320 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1d330 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
1d340 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1d350 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1d360 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1d370 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
1d380 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
1d390 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
1d3a0 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
1d3b0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
1d3c0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
1d3d0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
1d3e0 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
1d3f0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
1d400 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
1d410 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1d420 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51  d>.**.** <dt>[SQ
1d430 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1d440 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
1d450 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
1d460 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1d470 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1d480 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1d490 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
1d4a0 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20  reates it if.** 
1d4b0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
1d4c0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
1d4d0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
1d4e0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
1d4f0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
1d500 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1d510 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
1d520 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  /dd>.** </dl>.**
1d530 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1d540 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1d550 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1d560 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1d570 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1d580 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f  shown above or o
1d590 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e  ne of the combin
1d5a0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1d5b0 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77  ve combined.** w
1d5c0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
1d5d0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72  OPEN_NOMUTEX] or
1d5e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1d5f0 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 2c 0a  LLMUTEX] flags,.
1d600 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1d610 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1d620 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
1d630 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1d640 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1d650 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1d660 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1d670 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1d680 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1d690 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1d6a0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1d6b0 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1d6c0 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1d6d0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1d6e0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1d6f0 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53  e.  If the.** [S
1d700 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1d710 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1d720 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
1d730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
1d740 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
1d750 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1d760 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
1d770 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
1d780 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
1d790 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
1d7a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1d7b0 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  art-time..**.** 
1d7c0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1d7d0 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1d7e0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1d7f0 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
1d800 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
1d810 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1d820 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
1d830 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
1d840 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
1d850 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
1d860 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d870 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
1d880 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1d890 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1d8a0 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
1d8b0 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
1d8c0 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
1d8d0 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
1d8e0 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
1d8f0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
1d900 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
1d910 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1d920 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
1d930 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
1d940 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
1d950 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
1d960 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
1d970 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
1d980 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
1d990 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
1d9a0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
1d9b0 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
1d9c0 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
1d9d0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1d9e0 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
1d9f0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1da00 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 70  created.  This p
1da10 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
1da20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
1da30 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
1da40 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
1da50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1da60 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
1da70 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
1da80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1da90 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1daa0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1dab0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
1dac0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
1dad0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
1dae0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
1daf0 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
1db00 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1db10 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
1db20 20 75 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f   use.  If the fo
1db30 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
1db40 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1db50 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
1db60 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1db70 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
1db80 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
1db90 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
1dba0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
1dbb0 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
1dbc0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1dbd0 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
1dbe0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1dbf0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
1dc00 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
1dc10 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
1dc20 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
1dc30 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
1dc40 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
1dc50 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
1dc60 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
1dc70 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
1dc80 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
1dc90 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
1dca0 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
1dcb0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1dcc0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
1dcd0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1dce0 2a 0a 2a 2a 20 7b 48 31 32 37 30 31 7d 20 54 68  *.** {H12701} Th
1dcf0 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
1dd00 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1dd10 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20  n16()], and.**  
1dd20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1dd30 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
1dd40 72 66 61 63 65 73 20 63 72 65 61 74 65 20 61 20  rfaces create a 
1dd50 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
1dd60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1dd70 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
1dd80 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
1dd90 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66    the database f
1dda0 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  ile given in the
1ddb0 69 72 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ir first paramet
1ddc0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30  er..**.** {H1270
1ddd0 32 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  2} The filename 
1dde0 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
1ddf0 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
1de00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
1de10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1de20 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  ] and [sqlite3_o
1de30 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73  pen_v2()] and as
1de40 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20   UTF-16.**      
1de50 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76      in the nativ
1de60 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
1de70 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1de80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ()]..**.** {H127
1de90 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  03} A successful
1dea0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1deb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1dec0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1ded0 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
1dee0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
1def0 6e 5f 76 32 28 29 5d 20 77 72 69 74 65 73 20 61  n_v2()] writes a
1df00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
1df10 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  w.**          [d
1df20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1df30 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a  on] into *ppDb..
1df40 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 34 7d 20 54  **.** {H12704} T
1df50 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1df60 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1df70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
1df80 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1df90 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
1dfa0 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 5b  erfaces return [
1dfb0 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20  SQLITE_OK] upon 
1dfc0 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20  success,.**     
1dfd0 20 20 20 20 20 6f 72 20 61 6e 20 61 70 70 72 6f       or an appro
1dfe0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
1dff0 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a  de] on failure..
1e000 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 36 7d 20 54  **.** {H12706} T
1e010 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 20  he default text 
1e020 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e  encoding for a n
1e030 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65 61  ew database crea
1e040 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
1e050 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
1e060 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  pen()] or [sqlit
1e070 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69  e3_open_v2()] wi
1e080 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a  ll be UTF-8..**.
1e090 2a 2a 20 7b 48 31 32 37 30 37 7d 20 54 68 65 20  ** {H12707} The 
1e0a0 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63  default text enc
1e0b0 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20  oding for a new 
1e0c0 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64  database created
1e0d0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
1e0e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
1e0f0 31 36 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54  16()] will be UT
1e100 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  F-16..**.** {H12
1e110 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  709} The [sqlite
1e120 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74  3_open(F,D)] int
1e130 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61  erface is equiva
1e140 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  lent to.**      
1e150 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1e160 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77  n_v2(F,D,G,0)] w
1e170 68 65 72 65 20 74 68 65 20 47 20 70 61 72 61 6d  here the G param
1e180 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20  eter is.**      
1e190 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e      [SQLITE_OPEN
1e1a0 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c  _READWRITE]|[SQL
1e1b0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1e1c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 31 7d  ..**.** {H12711}
1e1d0 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
1e1e0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1e1f0 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
1e200 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  ] contains the.*
1e210 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76  *          bit v
1e220 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  alue [SQLITE_OPE
1e230 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e  N_READONLY] then
1e240 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1e250 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20   opened.**      
1e260 20 20 20 20 66 6f 72 20 72 65 61 64 69 6e 67 20      for reading 
1e270 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  only..**.** {H12
1e280 37 31 32 7d 20 49 66 20 74 68 65 20 47 20 70 61  712} If the G pa
1e290 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1e2a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
1e2b0 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74  G,V)] contains t
1e2c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
1e2d0 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
1e2e0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1e2f0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1e300 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20  se is opened.** 
1e310 20 20 20 20 20 20 20 20 20 72 65 61 64 69 6e 67           reading
1e320 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
1e330 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72  possible, or for
1e340 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66   reading only if
1e350 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1e360 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
1e370 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
1e380 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1e390 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 33 7d  ..**.** {H12713}
1e3a0 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
1e3b0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1e3c0 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
1e3d0 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20  ] omits the.**  
1e3e0 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
1e3f0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
1e400 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64  REATE] and the d
1e410 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1e420 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65  .**          pre
1e430 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61  viously exist, a
1e440 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1e450 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ned..**.** {H127
1e460 31 34 7d 20 49 66 20 74 68 65 20 47 20 70 61 72  14} If the G par
1e470 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
1e480 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1e490 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68  ,V)] contains th
1e4a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
1e4b0 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
1e4c0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64  OPEN_CREATE] and
1e4d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1e4e0 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  es not.**       
1e4f0 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78     previously ex
1e500 69 73 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 74  ist, then an att
1e510 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1e520 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20  create and.**   
1e530 20 20 20 20 20 20 20 69 6e 69 74 69 61 6c 69 7a         initializ
1e540 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  e the database..
1e550 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 37 7d 20 49  **.** {H12717} I
1e560 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  f the filename a
1e570 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
1e580 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1e590 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
1e5a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1e5b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1e5c0 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ()] is ":memory:
1e5d0 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61  ", then an priva
1e5e0 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  te,.**          
1e5f0 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65  ephemeral, in-me
1e600 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73  mory database is
1e610 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
1e620 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20   connection..** 
1e630 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49           <todo>I
1e640 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  s SQLITE_OPEN_CR
1e650 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e  EATE|SQLITE_OPEN
1e660 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69  _READWRITE requi
1e670 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
1e680 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  in sqlite3_open_
1e690 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  v2()?</todo>.**.
1e6a0 2a 2a 20 7b 48 31 32 37 31 39 7d 20 49 66 20 74  ** {H12719} If t
1e6b0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e  he filename is N
1e6c0 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
1e6d0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
1e6e0 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20  rivate,.**      
1e6f0 20 20 20 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e      ephemeral on
1e700 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
1e710 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 0a  ill be created..
1e720 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64  **          <tod
1e730 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e  o>Is SQLITE_OPEN
1e740 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f  _CREATE|SQLITE_O
1e750 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65  PEN_READWRITE re
1e760 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  quired.**       
1e770 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70     in sqlite3_op
1e780 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a  en_v2()?</todo>.
1e790 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 31 7d 20 54  **.** {H12721} T
1e7a0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1e7b0 6e 65 63 74 69 6f 6e 5d 20 63 72 65 61 74 65 64  nection] created
1e7c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   by [sqlite3_ope
1e7d0 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a  n_v2(F,D,G,V)].*
1e7e0 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
1e7f0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
1e800 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 64 65  _vfs] object ide
1e810 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 56  ntified by the V
1e820 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20   parameter,.**  
1e830 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 64          or the d
1e840 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1e850 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 66 20 56  vfs] object if V
1e860 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1e870 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32  er..**.** {H1272
1e880 33 7d 20 54 77 6f 20 5b 64 61 74 61 62 61 73 65  3} Two [database
1e890 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69   connections] wi
1e8a0 6c 6c 20 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f  ll share a commo
1e8b0 6e 20 63 61 63 68 65 20 69 66 20 62 6f 74 68 20  n cache if both 
1e8c0 77 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  were.**         
1e8d0 20 6f 70 65 6e 65 64 20 77 69 74 68 20 74 68 65   opened with the
1e8e0 20 73 61 6d 65 20 56 46 53 20 77 68 69 6c 65 20   same VFS while 
1e8f0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1e900 64 65 5d 20 77 61 73 20 65 6e 61 62 6c 65 64 20  de] was enabled 
1e910 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
1e920 69 66 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65  if both filename
1e930 73 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  s compare equal 
1e940 75 73 69 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61  using memcmp() a
1e950 66 74 65 72 20 68 61 76 69 6e 67 20 62 65 65 6e  fter having been
1e960 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 6f  .**          pro
1e970 63 65 73 73 65 64 20 62 79 20 74 68 65 20 5b 73  cessed by the [s
1e980 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 78 46 75  qlite3_vfs | xFu
1e990 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68  llPathname] meth
1e9a0 6f 64 20 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a  od of the VFS..*
1e9b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
1e9c0 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
1e9d0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1e9e0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1e9f0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1ea00 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1ea10 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1ea20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1ea30 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1ea40 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
1ea50 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
1ea60 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1ea70 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
1ea80 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
1ea90 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1eaa0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1eab0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1eac0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
1ead0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
1eae0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1eaf0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1eb00 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1eb10 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
1eb20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1eb30 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1eb40 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
1eb50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1eb60 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
1eb70 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
1eb80 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
1eb90 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
1eba0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1ebb0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
1ebc0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
1ebd0 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30 32 30   {H12800} <S6020
1ebe0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
1ebf0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
1ec00 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1ec10 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
1ec20 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
1ec30 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1ec40 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
1ec50 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
1ec60 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
1ec70 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
1ec80 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
1ec90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1eca0 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
1ecb0 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
1ecc0 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
1ecd0 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
1ece0 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
1ecf0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
1ed00 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1ed10 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
1ed20 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78    The sqlite3_ex
1ed30 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
1ed40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1ed50 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
1ed60 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
1ed70 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
1ed80 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1ed90 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
1eda0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
1edb0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
1edc0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  sabled..**.** Th
1edd0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
1ede0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
1edf0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
1ee00 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
1ee10 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
1ee20 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
1ee30 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
1ee40 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
1ee50 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d  spectively..** M
1ee60 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1ee70 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
1ee80 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
1ee90 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
1eea0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1eeb0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
1eec0 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
1eed0 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
1eee0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
1eef0 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
1ef00 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
1ef10 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
1ef20 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
1ef30 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
1ef40 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
1ef50 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ace functions..*
1ef60 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
1ef70 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
1ef80 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
1ef90 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
1efa0 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
1efb0 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
1efc0 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
1efd0 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
1efe0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
1eff0 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
1f000 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
1f010 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
1f020 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
1f030 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
1f040 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
1f050 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
1f060 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
1f070 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
1f080 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
1f090 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
1f0a0 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
1f0b0 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
1f0c0 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
1f0d0 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
1f0e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1f0f0 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
1f100 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
1f110 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
1f120 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
1f130 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
1f140 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
1f150 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
1f160 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
1f170 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
1f180 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
1f190 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
1f1a0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
1f1b0 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
1f1c0 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
1f1d0 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
1f1e0 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
1f1f0 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
1f200 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
1f210 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
1f220 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
1f230 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
1f240 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
1f250 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
1f260 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
1f270 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
1f280 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  e set..**.** INV
1f290 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1f2a0 48 31 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c  H12801} The [sql
1f2b0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d  ite3_errcode(D)]
1f2c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1f2d0 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a  ns the numeric.*
1f2e0 2a 20 20 20 20 20 20 20 20 20 20 5b 72 65 73 75  *          [resu
1f2f0 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  lt code] or [ext
1f300 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1f310 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
1f320 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20  recently.**     
1f330 20 20 20 20 20 66 61 69 6c 65 64 20 69 6e 74 65       failed inte
1f340 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63  rface call assoc
1f350 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
1f360 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f370 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ion] D..**.** {H
1f380 31 32 38 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  12802} The [sqli
1f390 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
1f3a0 63 6f 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61  code(D)] interfa
1f3b0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
1f3c0 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20  umeric.**       
1f3d0 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73     [extended res
1f3e0 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
1f3f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a  e most recently.
1f400 2a 2a 20 20 20 20 20 20 20 20 20 20 66 61 69 6c  **          fail
1f410 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  ed interface cal
1f420 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
1f430 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
1f440 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
1f450 2a 0a 2a 2a 20 7b 48 31 32 38 30 33 7d 20 54 68  *.** {H12803} Th
1f460 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  e [sqlite3_errms
1f470 67 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  g(D)] and [sqlit
1f480 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a  e3_errmsg16(D)].
1f490 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
1f4a0 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e  rfaces return En
1f4b0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
1f4c0 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
1f4d0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
1f4e0 68 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20  he error in the 
1f4f0 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20  mostly recently 
1f500 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65  failed interface
1f510 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20   call,.**       
1f520 20 20 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69     encoded as ei
1f530 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
1f540 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
1f550 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37  y..**.** {H12807
1f560 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  } The strings re
1f570 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1f580 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
1f590 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1f5a0 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
1f5b0 20 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69    are valid unti
1f5c0 6c 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74  l the next SQLit
1f5d0 65 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  e interface call
1f5e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d  ..**.** {H12808}
1f5f0 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f   Calls to API ro
1f600 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e  utines that do n
1f610 6f 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ot return an err
1f620 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
1f630 20 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73      (example: [s
1f640 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
1f650 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20  t()]) do not.** 
1f660 20 20 20 20 20 20 20 20 20 63 68 61 6e 67 65 20           change 
1f670 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  the error code o
1f680 72 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e  r message return
1f690 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1f6a0 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f    [sqlite3_errco
1f6b0 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
1f6c0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1f6d0 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
1f6e0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1f6f0 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
1f700 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a  _errmsg16()]..**
1f710 0a 2a 2a 20 7b 48 31 32 38 30 39 7d 20 49 6e 74  .** {H12809} Int
1f720 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65  erfaces that are
1f730 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20   not associated 
1f740 77 69 74 68 20 61 20 73 70 65 63 69 66 69 63 0a  with a specific.
1f750 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
1f760 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f770 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20  ] (examples:.** 
1f780 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1f790 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20  3_mprintf()] or 
1f7a0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
1f7b0 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a  shared_cache()].
1f7c0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e  **          do n
1f7d0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
1f7e0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1f7f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1f800 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1f810 2c 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  , [sqlite3_exten
1f820 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a  ded_errcode()],.
1f830 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1f840 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
1f850 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
1f860 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  sg16()]..*/.int 
1f870 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1f880 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
1f890 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
1f8a0 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
1f8b0 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
1f8c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
1f8d0 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
1f8e0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1f8f0 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
1f900 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1f910 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
1f920 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31  ement Object {H1
1f930 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a  3000} <H13010>.*
1f940 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
1f950 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
1f960 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1f970 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
1f980 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
1f990 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
1f9a0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
1f9b0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
1f9c0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
1f9d0 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
1f9e0 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
1f9f0 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
1fa00 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
1fa10 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
1fa20 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
1fa30 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
1fa40 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
1fa50 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
1fa60 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
1fa70 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
1fa80 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
1fa90 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1faa0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1fab0 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
1fac0 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
1fad0 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
1fae0 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
1faf0 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
1fb00 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1fb10 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
1fb20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
1fb30 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
1fb40 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
1fb50 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
1fb60 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
1fb70 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
1fb80 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1fb90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1fba0 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
1fbb0 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
1fbc0 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
1fbd0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1fbe0 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
1fbf0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1fc00 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1fc10 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
1fc20 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
1fc30 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
1fc40 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
1fc50 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
1fc60 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1fc70 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
1fc80 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1fc90 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
1fca0 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
1fcb0 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
1fcc0 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c  imits {H12760} <
1fcd0 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20600>.**.** Th
1fce0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1fcf0 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
1fd00 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
1fd10 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
1fd20 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
1fd30 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
1fd40 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
1fd50 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1fd60 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
1fd70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
1fd80 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
1fd90 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
1fda0 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
1fdb0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
1fdc0 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
1fdd0 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
1fde0 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
1fdf0 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
1fe00 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
1fe10 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
1fe20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1fe30 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
1fe40 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
1fe50 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
1fe60 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64   returns the old
1fe70 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66   limit..**.** If
1fe80 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
1fe90 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
1fea0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
1feb0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
1fec0 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61  For the limit ca
1fed0 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45  tegory of SQLITE
1fee0 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65  _LIMIT_XYZ there
1fef0 20 69 73 20 61 20 68 61 72 64 20 75 70 70 65 72   is a hard upper
1ff00 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 79  .** bound set by
1ff10 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20   a compile-time 
1ff20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1ff30 61 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54  acro named SQLIT
1ff40 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54  E_MAX_XYZ..** (T
1ff50 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
1ff60 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
1ff70 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
1ff80 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20  .** Attempts to 
1ff90 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
1ffa0 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
1ffb0 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
1ffc0 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
1ffd0 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
1ffe0 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a  d upper limit..*
1fff0 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69  *.** Run time li
20000 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
20010 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
20020 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
20030 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
20040 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
20050 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
20060 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
20070 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
20080 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
20090 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
200a0 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
200b0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
200c0 20 62 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77   be a.** webbrow
200d0 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
200e0 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
200f0 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
20100 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
20110 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
20120 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
20130 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
20140 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
20150 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
20160 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
20170 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
20180 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
20190 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
201a0 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
201b0 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
201c0 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
201d0 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
201e0 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
201f0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
20200 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
20210 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
20220 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
20230 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
20240 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
20250 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
20260 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
20270 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
20280 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
20290 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
202a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
202b0 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
202c0 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
202d0 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
202e0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
202f0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
20300 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
20310 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
20320 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
20330 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
20340 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
20350 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
20360 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20  .**.** {H12762} 
20370 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
20380 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69  l to [sqlite3_li
20390 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72  mit(D,C,V)] wher
203a0 65 20 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  e V is.**       
203b0 20 20 20 70 6f 73 69 74 69 76 65 20 63 68 61 6e     positive chan
203c0 67 65 73 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e  ges the limit on
203d0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e   the size of con
203e0 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a  struct C in the.
203f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
20400 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20410 5d 20 44 20 74 6f 20 74 68 65 20 6c 65 73 73 65  ] D to the lesse
20420 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68  r of V and the h
20430 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 20 20 20  ard upper.**    
20440 20 20 20 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74        bound on t
20450 68 65 20 73 69 7a 65 20 6f 66 20 43 20 74 68 61  he size of C tha
20460 74 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70  t is set at comp
20470 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ile-time..**.** 
20480 7b 48 31 32 37 36 36 7d 20 41 20 73 75 63 63 65  {H12766} A succe
20490 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
204a0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43  qlite3_limit(D,C
204b0 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 20  ,V)] where V is 
204c0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
204d0 20 20 20 20 20 6c 65 61 76 65 73 20 74 68 65 20       leaves the 
204e0 73 74 61 74 65 20 6f 66 20 74 68 65 20 5b 64 61  state of the [da
204f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20500 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a  n] D unchanged..
20510 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41  **.** {H12769} A
20520 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
20530 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
20540 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72  it(D,C,V)] retur
20550 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
20560 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
20570 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a  limit on the siz
20580 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43  e of construct C
20590 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
205a0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
205b0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 69  nnection] D as i
205c0 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20 74  t was prior to t
205d0 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20  he call..*/.int 
205e0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
205f0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
20600 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
20610 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
20620 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
20630 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d  egories {H12790}
20640 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59   <H12760>.** KEY
20650 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
20660 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63  tegory} {limit c
20670 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
20680 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
20690 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
206a0 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61  aspects of a [da
206b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
206c0 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  n].** that can b
206d0 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a  e limited in siz
206e0 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73  e by calls to [s
206f0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
20700 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73  .** The meanings
20710 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
20720 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f  limits are as fo
20730 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c  llows:.**.** <dl
20740 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
20750 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
20760 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
20770 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
20780 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
20790 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64  or table row.<dd
207a0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
207b0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
207c0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
207d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
207e0 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
207f0 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
20800 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
20810 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
20820 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
20830 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
20840 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
20850 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
20860 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
20870 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 6f  et of a SELECT o
20880 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
20890 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
208a0 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
208b0 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
208c0 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
208d0 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  use.</dd>.**.** 
208e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
208f0 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
20900 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
20910 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
20920 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
20930 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
20940 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
20950 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
20960 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
20970 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
20980 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
20990 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
209a0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
209b0 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
209c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
209d0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
209e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
209f0 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
20a00 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
20a10 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
20a20 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
20a30 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
20a40 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
20a50 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
20a60 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
20a70 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
20a80 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
20a90 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
20aa0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
20ab0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
20ac0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
20ad0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
20ae0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
20af0 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 64 61  r of attached da
20b00 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a  tabases.</dd>.**
20b10 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
20b20 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
20b30 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
20b40 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20b50 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
20b60 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
20b70 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a  to the LIKE or.*
20b80 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73  * GLOB operators
20b90 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
20ba0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
20bb0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
20bc0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20bd0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
20be0 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20  variables in an 
20bf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
20c00 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75  at can.** be bou
20c10 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  nd.</dd>.** </dl
20c20 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
20c30 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
20c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20c50 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
20c60 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
20c70 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
20c80 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
20c90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
20ca0 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
20cb0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
20cc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
20cd0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
20ce0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
20cf0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
20d00 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
20d10 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
20d20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
20d30 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
20d40 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
20d50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
20d60 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
20d70 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
20d80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
20d90 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
20da0 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
20db0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
20dc0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
20dd0 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
20de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
20df0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
20e00 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a  ER           9..
20e10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20e20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
20e30 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30   Statement {H130
20e40 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20  10} <S10000>.** 
20e50 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
20e60 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
20e70 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
20e80 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
20e90 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
20ea0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
20eb0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
20ec0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
20ed0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
20ee0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
20ef0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
20f00 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
20f10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
20f20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
20f30 2a 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f  ** prior call to
20f40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
20f50 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
20f60 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
20f70 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
20f80 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
20f90 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
20fa0 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
20fb0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
20fc0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
20fd0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
20fe0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
20ff0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
21000 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
21010 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
21020 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
21030 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
21040 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
21050 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
21060 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
21070 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  6..**.** If the 
21080 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
21090 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
210a0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
210b0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
210c0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
210d0 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65  inator. If nByte
210e0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
210f0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
21100 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
21110 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
21120 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68  d from zSql.  Wh
21130 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
21140 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
21150 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
21160 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
21170 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
21180 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
21190 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
211a0 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
211b0 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
211c0 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
211d0 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
211e0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
211f0 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
21200 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
21210 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
21220 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
21230 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
21240 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
21250 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
21260 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
21270 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
21280 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
21290 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
212a0 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
212b0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
212c0 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20  or bytes..**.** 
212d0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
212e0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
212f0 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20  first byte past 
21300 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a  the end of the.*
21310 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  * first SQL stat
21320 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
21330 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
21340 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  nly compile the 
21350 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65  first.** stateme
21360 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
21370 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
21380 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20  ointing to what 
21390 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d  remains.** uncom
213a0 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70  piled..**.** *pp
213b0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
213c0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
213d0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
213e0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
213f0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
21400 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
21410 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65  step()].  If the
21420 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
21430 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
21440 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74  * to NULL.  If t
21450 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
21460 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
21470 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
21480 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
21490 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
214a0 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
214b0 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
214c0 7b 41 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c  {A13018} The cal
214d0 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
214e0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
214f0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
21500 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
21510 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
21520 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
21530 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
21540 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
21550 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  t..**.** On succ
21560 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
21570 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74   is returned, ot
21580 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
21590 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
215a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
215b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
215c0 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
215d0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
215e0 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
215f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
21600 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
21610 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
21620 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
21630 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
21640 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
21650 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
21660 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
21670 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65  raged..** In the
21680 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
21690 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
216a0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
216b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
216c0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
216d0 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
216e0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
216f0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
21700 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
21710 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
21720 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
21730 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20   to.** behave a 
21740 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
21750 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  wo ways:.**.** <
21760 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49  ol>.** <li>.** I
21770 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
21780 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
21790 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
217a0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
217b0 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
217c0 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
217d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
217e0 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
217f0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
21800 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
21810 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
21820 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20  n it again.  If 
21830 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63  the schema has c
21840 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77  hanged in.** a w
21850 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  ay that makes th
21860 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c  e statement no l
21870 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71  onger valid, [sq
21880 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
21890 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75  ll still.** retu
218a0 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  rn [SQLITE_SCHEM
218b0 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20  A].  But unlike 
218c0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
218d0 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  ior, [SQLITE_SCH
218e0 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61  EMA] is.** now a
218f0 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43   fatal error.  C
21900 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
21910 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67  prepare_v2()] ag
21920 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b  ain will not mak
21930 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67  e the.** error g
21940 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75  o away.  Note: u
21950 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
21960 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
21970 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65  e text.** of the
21980 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74   parsing error t
21990 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
219a0 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
219b0 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c  ] return..** </l
219c0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
219d0 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f   When an error o
219e0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
219f0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
21a00 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
21a10 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
21a20 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
21a30 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
21a40 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20  s].  The legacy 
21a50 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
21a60 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
21a70 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
21a80 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
21a90 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
21aa0 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
21ab0 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61  and you would ha
21ac0 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
21ad0 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
21ae0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e  ite3_reset()] in
21af0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e   order.** to fin
21b00 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
21b10 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
21b20 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
21b30 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
21b40 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
21b50 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
21b60 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
21b70 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
21b80 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
21b90 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ol>.**.**
21ba0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
21bb0 2a 2a 20 7b 48 31 33 30 31 31 7d 20 54 68 65 20  ** {H13011} The 
21bc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21bd0 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61  (db,zSql,...)] a
21be0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
21bf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21c00 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  v2(db,zSql,...)]
21c10 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65   interfaces inte
21c20 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20  rpret the.**    
21c30 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68        text in th
21c40 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74  eir zSql paramet
21c50 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a  er as UTF-8..**.
21c60 2a 2a 20 7b 48 31 33 30 31 32 7d 20 54 68 65 20  ** {H13012} The 
21c70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21c80 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  16(db,zSql,...)]
21c90 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
21ca0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21cb0 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e  e16_v2(db,zSql,.
21cc0 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  ..)] interfaces 
21cd0 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
21ce0 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69            text i
21cf0 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72  n their zSql par
21d00 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31 36  ameter as UTF-16
21d10 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
21d20 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
21d30 20 7b 48 31 33 30 31 33 7d 20 49 66 20 74 68 65   {H13013} If the
21d40 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
21d50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
21d60 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e  are_v2(db,zSql,n
21d70 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  Byte,...)].**   
21d80 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76         and its v
21d90 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20  ariants is less 
21da0 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53  than zero, the S
21db0 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20  QL text is.**   
21dc0 20 20 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d         read from
21dd0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
21de0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
21df0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
21e00 2a 0a 2a 2a 20 7b 48 31 33 30 31 34 7d 20 49 66  *.** {H13014} If
21e10 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
21e20 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
21e30 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
21e40 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a  ql,nByte,...)].*
21e50 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69  *          and i
21e60 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e  ts variants is n
21e70 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
21e80 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73  n at most nBytes
21e90 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20   bytes of.**    
21ea0 20 20 20 20 20 20 53 51 4c 20 74 65 78 74 20 69        SQL text i
21eb0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
21ec0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d  ..**.** {H13015}
21ed0 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   In [sqlite3_pre
21ee0 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
21ef0 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64  N,P,pzTail)] and
21f00 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a   its variants.**
21f10 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65            if the
21f20 20 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78 74   zSql input text
21f30 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74   contains more t
21f40 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 74  han one SQL stat
21f50 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  ement.**        
21f60 20 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20    and pzTail is 
21f70 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a  not NULL, then *
21f80 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
21f90 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a  o point to the.*
21fa0 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74  *          first
21fb0 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65   byte past the e
21fc0 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
21fd0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
21fe0 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20   zSql..**       
21ff0 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f     <todo>What do
22000 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74  es *pzTail point
22010 20 74 6f 20 69 66 20 74 68 65 72 65 20 69 73 20   to if there is 
22020 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f  one statement?</
22030 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  todo>.**.** {H13
22040 30 31 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  016} A successfu
22050 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
22060 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
22070 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e  ,zSql,N,ppStmt,.
22080 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
22090 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
220a0 61 72 69 61 6e 74 73 20 77 72 69 74 65 73 20 69  ariants writes i
220b0 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f  nto *ppStmt a po
220c0 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a  inter to a new.*
220d0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
220e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
220f0 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  or a pointer to 
22100 4e 55 4c 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e  NULL if zSql con
22110 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  tains.**        
22120 20 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20    nothing other 
22130 74 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 20  than whitespace 
22140 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a  or comments..**.
22150 2a 2a 20 7b 48 31 33 30 31 39 7d 20 54 68 65 20  ** {H13019} The 
22160 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22170 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
22180 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
22190 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  s return.**     
221a0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
221b0 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61   or an appropria
221c0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
221d0 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  upon failure..**
221e0 0a 2a 2a 20 7b 48 31 33 30 32 31 7d 20 42 65 66  .** {H13021} Bef
221f0 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ore [sqlite3_pre
22200 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  pare(db,zSql,nBy
22210 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c  te,ppStmt,pzTail
22220 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20  )] or its.**    
22230 20 20 20 20 20 20 76 61 72 69 61 6e 74 73 20 72        variants r
22240 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20  eturns an error 
22250 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72  (any value other
22260 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
22270 5d 29 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ]),.**          
22280 74 68 65 79 20 66 69 72 73 74 20 73 65 74 20 2a  they first set *
22290 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a  ppStmt to NULL..
222a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
222b0 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
222c0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
222d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
222e0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
222f0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
22300 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
22310 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
22320 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
22330 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
22340 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
22350 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
22360 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
22370 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
22380 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
22390 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
223a0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
223b0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
223c0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
223d0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
223e0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
223f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
22400 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
22410 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
22420 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
22430 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
22440 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
22450 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
22460 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
22470 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
22480 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
22490 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
224a0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
224b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
224c0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
224d0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
224e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
224f0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
22500 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
22510 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
22520 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
22530 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
22540 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
22550 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
22560 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
22570 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
22580 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
22590 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
225a0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
225b0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
225c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
225d0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
225e0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
225f0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
22600 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
22610 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
22620 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
22630 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
22640 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
22650 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
22660 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
22670 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
22680 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
22690 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
226a0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
226b0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
226c0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
226d0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
226e0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
226f0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
22700 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
22710 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
22720 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
22730 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
22740 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
22750 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
22760 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
22770 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
22780 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
22790 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
227a0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
227b0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
227c0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
227d0 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
227e0 20 53 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48   SQL {H13100} <H
227f0 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  13000>.**.** Thi
22800 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
22810 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
22820 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
22830 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
22840 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
22850 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
22860 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22870 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
22880 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
22890 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
228a0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
228b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
228c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
228d0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  2()]..**.** INVA
228e0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
228f0 31 33 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70  13101} If the [p
22900 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22910 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65  t] passed as the
22920 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
22930 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
22940 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
22950 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
22960 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
22970 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
22980 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
22990 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
229a0 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ], then [sqlite3
229b0 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a  _sql()] returns.
229c0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f  **          a po
229d0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
229e0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
229f0 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55  g containing a U
22a00 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a  TF-8 rendering.*
22a10 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
22a20 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73  e original SQL s
22a30 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
22a40 7b 48 31 33 31 30 32 7d 20 49 66 20 74 68 65 20  {H13102} If the 
22a50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22a60 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20 74  ent] passed as t
22a70 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
22a80 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
22a90 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63  te3_sql()] was c
22aa0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
22ab0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
22ac0 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20  epare()] or.**  
22ad0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
22ae0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
22af0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c  hen [sqlite3_sql
22b00 28 29 5d 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ()] returns a NU
22b10 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
22b20 2a 20 7b 48 31 33 31 30 33 7d 20 54 68 65 20 73  * {H13103} The s
22b30 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62  tring returned b
22b40 79 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53  y [sqlite3_sql(S
22b50 29 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  )] is valid unti
22b60 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  l the.**        
22b70 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
22b80 65 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65  ement] S is dele
22b90 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
22ba0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e  e3_finalize(S)].
22bb0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
22bc0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
22bd0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
22be0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22bf0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
22c00 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
22c10 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32  t {H15000} <S202
22c20 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
22c30 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
22c40 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
22c50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
22c60 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
22c70 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
22c80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
22c90 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
22ca0 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
22cb0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
22cc0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
22cd0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
22ce0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
22cf0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
22d00 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c  s it stores. Val
22d10 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
22d20 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
22d30 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
22d40 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
22d50 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
22d60 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
22d70 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
22d80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
22d90 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
22da0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
22db0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
22dc0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
22dd0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
22de0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
22df0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
22e00 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
22e10 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
22e20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
22e30 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
22e40 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
22e50 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
22e60 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
22e70 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
22e80 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
22e90 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
22ea0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
22eb0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
22ec0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
22ed0 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
22ee0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
22ef0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
22f00 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
22f10 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
22f20 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75  .  A internal mu
22f30 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
22f40 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
22f50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
22f60 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
22f70 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
22f80 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
22f90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
22fa0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
22fb0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
22fc0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
22fd0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
22fe0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
22ff0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
23000 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
23010 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
23020 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
23030 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
23040 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
23050 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
23060 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
23070 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
23080 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
23090 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
230a0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
230b0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
230c0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
230d0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
230e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
230f0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
23100 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
23110 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
23120 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
23130 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
23140 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
23150 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
23160 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
23170 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
23180 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20  between between 
23190 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
231a0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
231b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
231c0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
231d0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
231e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
231f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
23200 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
23210 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
23220 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
23230 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
23240 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
23250 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
23260 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
23270 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
23280 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
23290 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
232a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
232b0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
232c0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
232d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
232e0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
232f0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
23300 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
23310 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
23320 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
23330 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
23340 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
23350 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
23360 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
23370 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
23380 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
23390 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
233a0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
233b0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
233c0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
233d0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
233e0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
233f0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20   Context Object 
23400 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30  {H16001} <S20200
23410 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  >.**.** The cont
23420 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
23430 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
23440 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
23450 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
23460 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
23470 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61    A pointer to a
23480 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
23490 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
234a0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
234b0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
234c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
234d0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
234e0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
234f0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
23500 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
23510 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
23520 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
23530 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
23540 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
23550 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
23560 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
23570 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
23580 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
23590 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
235a0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
235b0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
235c0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
235d0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
235e0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
235f0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
23600 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
23610 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
23620 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
23630 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
23640 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
23650 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
23660 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b  red Statements {
23670 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13500} <S70300>
23680 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
23690 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
236a0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
236b0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
236c0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
236d0 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
236e0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
236f0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
23700 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49  binding}.**.** I
23710 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67  n the SQL string
23720 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  s input to [sqli
23730 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
23740 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
23750 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
23760 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
23770 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69  by a parameter i
23780 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66  n one of these f
23790 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  orms:.**.** <ul>
237a0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
237b0 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
237c0 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
237d0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
237e0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
237f0 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65  ** In the parame
23800 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20  ter forms shown 
23810 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20  above NNN is an 
23820 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
23830 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61  .** and VVV is a
23840 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20  n alpha-numeric 
23850 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20  parameter name. 
23860 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
23870 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
23880 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
23890 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
238a0 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
238b0 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
238c0 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
238d0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
238e0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
238f0 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
23900 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
23910 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
23920 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
23930 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
23940 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
23950 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
23960 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
23970 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
23980 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
23990 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
239a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
239b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
239c0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
239d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
239e0 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20   be set..** The 
239f0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
23a00 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
23a10 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20  dex of 1.  When 
23a20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
23a30 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
23a40 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
23a50 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
23a60 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
23a70 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
23a80 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
23a90 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
23aa0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65  currence..** The
23ab0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
23ac0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
23ad0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
23ae0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
23af0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
23b00 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
23b10 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20  f desired.  The 
23b20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
23b30 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
23b40 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
23b50 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76  NN..** The NNN v
23b60 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
23b70 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
23b80 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
23b90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
23ba0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
23bb0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
23bc0 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
23bd0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  )..**.** The thi
23be0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
23bf0 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
23c00 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
23c10 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73  r..**.** In thos
23c20 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
23c30 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
23c40 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
23c50 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
23c60 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
23c70 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
23c80 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
23c90 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
23ca0 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
23cb0 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
23cc0 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
23cd0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
23ce0 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  s..** If the fou
23cf0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
23d00 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c   negative, the l
23d10 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
23d20 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
23d30 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
23d40 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
23d50 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
23d60 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61  *.** The fifth a
23d70 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
23d80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
23d90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
23da0 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
23db0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
23dc0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
23dd0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
23de0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
23df0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
23e00 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
23e10 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66  shed with it. If
23e20 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
23e30 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
23e40 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
23e50 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
23e60 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
23e70 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
23e80 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
23e90 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
23ea0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
23eb0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
23ec0 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  reed..** If the 
23ed0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
23ee0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
23ef0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
23f00 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
23f10 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
23f20 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
23f30 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
23f40 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
23f50 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
23f60 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
23f70 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
23f80 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
23f90 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
23fa0 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
23fb0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
23fc0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
23fd0 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f  roes.  A zeroblo
23fe0 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
23ff0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
24000 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
24010 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
24020 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
24030 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
24040 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
24050 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
24060 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
24070 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
24080 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
24090 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
240a0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
240b0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
240c0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
240d0 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
240e0 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61  ** A negative va
240f0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
24100 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
24110 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
24120 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  OB..**.** The sq
24130 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
24140 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
24150 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20  called after.** 
24160 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24170 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20  _v2()] (and its 
24180 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71  variants) or [sq
24190 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
241a0 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71  nd.** before [sq
241b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
241c0 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e  * Bindings are n
241d0 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
241e0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
241f0 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
24200 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
24210 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
24220 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
24230 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
24240 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
24250 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
24260 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20  r an error code 
24270 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67  if.** anything g
24280 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c  oes wrong.  [SQL
24290 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
242a0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
242b0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
242c0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
242d0 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  .  [SQLITE_NOMEM
242e0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
242f0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
24300 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
24310 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  SE] might be ret
24320 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72  urned if these r
24330 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
24340 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75  ed on a.** virtu
24350 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20  al machine that 
24360 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61  is the wrong sta
24370 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20  te or which has 
24380 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e  already been fin
24390 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63  alized..** Detec
243a0 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69  tion of misuse i
243b0 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41  s unreliable.  A
243c0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
243d0 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a  ld not depend.**
243e0 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   on SQLITE_MISUS
243f0 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49  E returns.  SQLI
24400 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74  TE_MISUSE is int
24410 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74  ended to indicat
24420 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65  e a.** a logic e
24430 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c  rror in the appl
24440 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65  ication.  Future
24450 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
24460 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e  ite might.** pan
24470 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72  ic rather than r
24480 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
24490 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  USE..**.** See a
244a0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
244b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
244c0 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
244d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
244e0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
244f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
24500 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
24510 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
24520 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 36  S:.**.** {H13506
24530 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65  } The [SQL state
24540 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72  ment compiler] r
24550 65 63 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73  ecognizes tokens
24560 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a   of the forms.**
24570 20 20 20 20 20 20 20 20 20 20 22 3f 22 2c 20 22            "?", "
24580 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22  ?NNN", "$VVV", "
24590 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56  :VVV", and "@VVV
245a0 22 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74  " as SQL paramet
245b0 65 72 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ers,.**         
245c0 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e   where NNN is an
245d0 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e  y sequence of on
245e0 65 20 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73  e or more digits
245f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
24600 20 77 68 65 72 65 20 56 56 56 20 69 73 20 61 6e   where VVV is an
24610 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e  y sequence of on
24620 65 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e  e or more alphan
24630 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20  umeric.**       
24640 20 20 20 63 68 61 72 61 63 74 65 72 73 20 6f 72     characters or
24650 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79   "::" optionally
24660 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 73   followed by a s
24670 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
24680 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20  .**          no 
24690 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61  spaces and conta
246a0 69 6e 65 64 20 77 69 74 68 69 6e 20 70 61 72 65  ined within pare
246b0 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ntheses..**.** {
246c0 48 31 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74  H13509} The init
246d0 69 61 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  ial value of an 
246e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
246f0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   NULL..**.** {H1
24700 33 35 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20  3512} The index 
24710 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61  of an "?" SQL pa
24720 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c  rameter is one l
24730 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a  arger than the.*
24740 2a 20 20 20 20 20 20 20 20 20 20 6c 61 72 67 65  *          large
24750 73 74 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20  st index of SQL 
24760 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
24770 20 6c 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a   left, or 1 if.*
24780 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 22  *          the "
24790 3f 22 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f  ?" is the leftmo
247a0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
247b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 35 7d  ..**.** {H13515}
247c0 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
247d0 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61   "?NNN" SQL para
247e0 6d 65 74 65 72 20 69 73 20 74 68 65 20 69 6e 74  meter is the int
247f0 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20  eger NNN..**.** 
24800 7b 48 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64  {H13518} The ind
24810 65 78 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c  ex of an ":VVV",
24820 20 22 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56   "$VVV", or "@VV
24830 56 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  V" SQL parameter
24840 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
24850 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
24860 69 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73  index of leftmos
24870 74 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66  t occurrences of
24880 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
24890 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c        parameter,
248a0 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61   or one more tha
248b0 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e  n the largest in
248c0 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20  dex over all.** 
248d0 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
248e0 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20  ers to the left 
248f0 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20 66  if this is the f
24900 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a  irst occurrence.
24910 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
24920 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c 20 6f  his parameter, o
24930 72 20 31 20 69 66 20 74 68 69 73 20 69 73 20 74  r 1 if this is t
24940 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61 72 61  he leftmost para
24950 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  meter..**.** {H1
24960 33 35 32 31 7d 20 54 68 65 20 5b 53 51 4c 20 73  3521} The [SQL s
24970 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
24980 72 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  r] fails with an
24990 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a   [SQLITE_RANGE].
249a0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f  **          erro
249b0 72 20 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f  r if the index o
249c0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
249d0 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
249e0 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  1.**          or
249f0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
24a00 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53  e compile-time S
24a10 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42  QLITE_MAX_VARIAB
24a20 4c 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20  LE_NUMBER.**    
24a30 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e        parameter.
24a40 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 34 7d 20  .**.** {H13524} 
24a50 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
24a60 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
24a70 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56  lite3_bind(S,N,V
24a80 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
24a90 20 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65     associate the
24aa0 20 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c   value V with al
24ab0 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  l SQL parameters
24ac0 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20   having an.**   
24ad0 20 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20         index of 
24ae0 4e 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  N in the [prepar
24af0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
24b00 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 37 7d 20  .**.** {H13527} 
24b10 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
24b20 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
24b30 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e  lite3_bind(S,N,.
24b40 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
24b50 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20   override prior 
24b60 63 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73  calls with the s
24b70 61 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20  ame values of S 
24b80 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  and N..**.** {H1
24b90 33 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65  3530} Bindings e
24ba0 73 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73  stablished by [s
24bb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24bc0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
24bd0 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  S,...)].**      
24be0 20 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f      persist acro
24bf0 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ss calls to [sql
24c00 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a  ite3_reset(S)]..
24c10 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 33 7d 20 49  **.** {H13533} I
24c20 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
24c30 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
24c40 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
24c50 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
24c60 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
24c70 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
24c80 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
24c90 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
24ca0 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69  ,L,D)] SQLite bi
24cb0 6e 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a  nds the first L.
24cc0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65  **          byte
24cd0 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  s of the BLOB or
24ce0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
24cf0 74 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a  to by V, when L.
24d00 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e  **          is n
24d10 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
24d20 2a 2a 20 7b 48 31 33 35 33 36 7d 20 49 6e 20 63  ** {H13536} In c
24d30 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
24d40 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
24d50 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ,L,D)] or.**    
24d60 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
24d70 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
24d80 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69  ,L,D)] SQLite bi
24d90 6e 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a  nds characters.*
24da0 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
24db0 56 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  V through the fi
24dc0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
24dd0 65 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67  er when L is neg
24de0 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
24df0 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3539} In calls t
24e00 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
24e10 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
24e20 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
24e30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24e40 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
24e50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
24e60 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
24e70 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68  6(S,N,V,L,D)] wh
24e80 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63  en D is the spec
24e90 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ial.**          
24ea0 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45  constant [SQLITE
24eb0 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65  _STATIC], SQLite
24ec0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
24ed0 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20  e value V.**    
24ee0 20 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e        is held in
24ef0 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65   static unmanage
24f00 64 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c  d space that wil
24f10 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20  l not change.** 
24f20 20 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20           during 
24f30 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20  the lifetime of 
24f40 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a  the binding..**.
24f50 2a 2a 20 7b 48 31 33 35 34 32 7d 20 49 6e 20 63  ** {H13542} In c
24f60 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
24f70 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56  _bind_blob(S,N,V
24f80 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,L,D)],.**      
24f90 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
24fa0 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
24fb0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
24fc0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
24fd0 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
24fe0 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68  D)] when D is th
24ff0 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20  e special.**    
25000 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b        constant [
25010 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
25020 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d  ], the routine m
25030 61 6b 65 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  akes a.**       
25040 20 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20     private copy 
25050 6f 66 20 74 68 65 20 76 61 6c 75 65 20 56 20 62  of the value V b
25060 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
25070 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 35 7d  ..**.** {H13545}
25080 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
25090 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
250a0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
250b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
250c0 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
250d0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
250e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
250f0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
25100 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
25110 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
25120 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75  **          a fu
25130 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69  nction, SQLite i
25140 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63  nvokes that func
25150 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20  tion to destroy 
25160 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
25170 76 61 6c 75 65 20 56 20 61 66 74 65 72 20 69 74  value V after it
25180 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
25190 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e  ing the value V.
251a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 38 7d 20  .**.** {H13548} 
251b0 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
251c0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
251d0 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65  ob(S,N,V,L)] the
251e0 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20   value bound.** 
251f0 20 20 20 20 20 20 20 20 20 69 73 20 61 20 42 4c           is a BL
25200 4f 42 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f  OB of L bytes, o
25210 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
25220 42 4c 4f 42 20 69 66 20 4c 20 69 73 20 6e 65 67  BLOB if L is neg
25230 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
25240 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3551} In calls t
25250 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
25260 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68  value(S,N,V)] th
25270 65 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79  e V argument may
25280 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20  .**          be 
25290 65 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63  either a [protec
252a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
252b0 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a  e] object or an.
252c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70  **          [unp
252d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
252e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a  _value] object..
252f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
25300 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
25310 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
25320 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
25330 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
25340 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
25350 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
25360 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
25370 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
25380 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
25390 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
253a0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
253b0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
253c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
253d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
253e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
253f0 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
25400 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
25410 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
25420 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
25430 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
25440 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
25450 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
25460 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
25470 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
25480 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
25490 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
254a0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
254b0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
254c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
254d0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
254e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
254f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
25500 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
25510 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
25520 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25530 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
25540 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33   Parameters {H13
25550 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  600} <S70300>.**
25560 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
25570 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
25580 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
25590 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
255a0 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
255b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
255c0 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
255d0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
255e0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
255f0 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
25600 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
25610 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
25620 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
25630 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
25640 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
25650 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
25660 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
25670 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
25680 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   time..**.** Thi
25690 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
256a0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
256b0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
256c0 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
256d0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
256e0 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
256f0 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
25700 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
25710 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
25720 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
25730 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
25740 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
25750 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
25760 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
25770 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  n the list..**.*
25780 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
25790 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
257a0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
257b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
257c0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
257d0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
257e0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
257f0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
25800 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
25810 2a 0a 2a 2a 20 7b 48 31 33 36 30 31 7d 20 54 68  *.** {H13601} Th
25820 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
25830 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
25840 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
25850 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
25860 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e    the largest in
25870 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70  dex of all SQL p
25880 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65  arameters in the
25890 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
258a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
258b0 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20 63  ] S, or 0 if S c
258c0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70  ontains no SQL p
258d0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e  arameters..*/.in
258e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
258f0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
25900 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
25910 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25920 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
25930 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30  arameter {H13620
25940 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
25950 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
25960 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
25970 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  to the name of t
25980 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20  he n-th.** [SQL 
25990 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20  parameter] in a 
259a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
259b0 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72  ent]..** SQL par
259c0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
259d0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
259e0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
259f0 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
25a00 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
25a10 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
25a20 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
25a30 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
25a40 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
25a50 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
25a60 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
25a70 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
25a80 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
25a90 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
25aa0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a   of the name..**
25ab0 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   Parameters of t
25ac0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
25ad0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
25ae0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
25af0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
25b00 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f  also referred to
25b10 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   as "anonymous p
25b20 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
25b30 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74  * The first host
25b40 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
25b50 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
25b60 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  t 0..**.** If th
25b70 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74  e value n is out
25b80 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
25b90 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74  the n-th paramet
25ba0 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
25bb0 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
25bc0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72  returned.  The r
25bd0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
25be0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
25bf0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
25c00 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
25c10 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
25c20 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
25c30 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
25c40 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
25c50 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
25c60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25c70 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
25c80 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
25c90 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
25ca0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
25cb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
25cc0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
25cd0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
25ce0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
25cf0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
25d00 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
25d10 2a 2a 20 7b 48 31 33 36 32 31 7d 20 54 68 65 20  ** {H13621} The 
25d20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
25d30 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e  rameter_name(S,N
25d40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
25d50 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
25d60 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
25d70 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f  ng of the name o
25d80 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
25d90 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  ter in.**       
25da0 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
25db0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
25dc0 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72  ving index N, or
25dd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c  .**          NUL
25de0 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f  L if there is no
25df0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77   SQL parameter w
25e00 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69  ith index N or i
25e10 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
25e20 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68    parameter with
25e30 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61   index N is an a
25e40 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
25e50 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74  er "?"..*/.const
25e60 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
25e70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
25e80 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
25e90 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
25ea0 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
25eb0 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
25ec0 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20  th A Given Name 
25ed0 7b 48 31 33 36 34 30 7d 20 3c 53 37 30 33 30 30  {H13640} <S70300
25ee0 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  >.**.** Return t
25ef0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
25f00 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
25f10 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68  en its name.  Th
25f20 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
25f30 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
25f40 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
25f50 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
25f60 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
25f70 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
25f80 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
25f90 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65   A zero.** is re
25fa0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
25fb0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
25fc0 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70  is found.  The p
25fd0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
25fe0 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
25ff0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
26000 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
26010 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
26020 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
26030 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
26040 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26050 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
26060 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
26070 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
26080 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
26090 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
260a0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
260b0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
260c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
260d0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
260e0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
260f0 2a 20 7b 48 31 33 36 34 31 7d 20 54 68 65 20 5b  * {H13641} The [
26100 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
26110 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e  ameter_index(S,N
26120 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
26130 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
26140 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 53 51   the index of SQ
26150 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  L parameter in t
26160 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26170 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20  tement].**      
26180 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65      S whose name
26190 20 6d 61 74 63 68 65 73 20 74 68 65 20 55 54 46   matches the UTF
261a0 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20  -8 string N, or 
261b0 30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a  0 if there is.**
261c0 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74            no mat
261d0 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ch..*/.int sqlit
261e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
261f0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
26200 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
26210 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
26220 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
26230 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
26240 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
26250 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20  tement {H13660} 
26260 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43  <S70300>.**.** C
26270 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
26280 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
26290 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
262a0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
262b0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
262c0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
262d0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
262e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
262f0 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20  t]..** Use this 
26300 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
26310 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
26320 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  ters to NULL..**
26330 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
26340 2a 2a 0a 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54  **.** {H13661} T
26350 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  he [sqlite3_clea
26360 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69  r_bindings(S)] i
26370 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
26380 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20  all SQL.**      
26390 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 62 69      parameter bi
263a0 6e 64 69 6e 67 73 20 69 6e 20 74 68 65 20 5b 70  ndings in the [p
263b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
263c0 74 5d 20 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c  t] S back to NUL
263d0 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
263e0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
263f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
26400 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26410 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
26420 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
26430 53 65 74 20 7b 48 31 33 37 31 30 7d 20 3c 53 31  Set {H13710} <S1
26440 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  0700>.**.** Retu
26450 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
26460 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
26470 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
26480 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
26490 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
264a0 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  t]. This routine
264b0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
264c0 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
264d0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
264e0 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
264f0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
26500 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
26510 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
26520 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d  :.**.** {H13711}
26530 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
26540 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69  lumn_count(S)] i
26550 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26560 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
26570 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d  *          colum
26580 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
26590 20 73 65 74 20 67 65 6e 65 72 61 74 65 64 20 62   set generated b
265a0 79 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  y the [prepared 
265b0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a  statement] S,.**
265c0 20 20 20 20 20 20 20 20 20 20 6f 72 20 30 20 69            or 0 i
265d0 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e  f S does not gen
265e0 65 72 61 74 65 20 61 20 72 65 73 75 6c 74 20 73  erate a result s
265f0 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
26600 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
26610 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
26620 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
26630 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
26640 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
26650 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31  Set {H13720} <S1
26660 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0700>.**.** Thes
26670 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
26680 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
26690 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
266a0 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
266b0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
266c0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
266d0 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71  atement.  The sq
266e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
266f0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
26700 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
26710 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
26720 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
26730 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
26740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
26750 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
26760 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
26770 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
26780 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  F-16 string.  Th
26790 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
267a0 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
267b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
267c0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
267d0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
267e0 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63  atement. The sec
267f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
26800 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
26810 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74  umber.  The left
26820 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
26830 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54  umber 0..**.** T
26840 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
26850 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
26860 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
26870 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
26880 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
26890 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
268a0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
268b0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  ] or until the n
268c0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
268d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
268e0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
268f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
26900 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
26910 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c  mn..**.** If sql
26920 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
26930 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
26940 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
26950 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
26960 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
26970 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
26980 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
26990 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
269a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
269b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
269c0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
269d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
269e0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
269f0 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
26a00 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
26a10 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
26a20 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
26a30 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
26a40 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
26a50 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
26a60 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
26a70 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
26a80 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
26a90 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
26aa0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a  o the next..**.*
26ab0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
26ac0 0a 2a 2a 20 7b 48 31 33 37 32 31 7d 20 41 20 73  .** {H13721} A s
26ad0 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
26ae0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
26af0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26b00 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  (S,N)].**       
26b10 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74     interface ret
26b20 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  urns the name of
26b30 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
26b40 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20  (where 0 is.**  
26b50 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74          the left
26b60 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72  most column) for
26b70 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
26b80 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
26b90 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
26ba0 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a  tement] S as a z
26bb0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
26bc0 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
26bd0 2a 2a 20 7b 48 31 33 37 32 33 7d 20 41 20 73 75  ** {H13723} A su
26be0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
26bf0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
26c00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
26c10 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  6(S,N)].**      
26c20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65      interface re
26c30 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f  turns the name o
26c40 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
26c50 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20   (where 0 is.** 
26c60 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66           the lef
26c70 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f  tmost column) fo
26c80 72 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  r the result set
26c90 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
26ca0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
26cb0 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20  atement] S as a 
26cc0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
26cd0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
26ce0 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65            in the
26cf0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
26d00 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32  er..**.** {H1372
26d10 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
26d20 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61  column_name()] a
26d30 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
26d40 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20  mn_name16()].** 
26d50 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
26d60 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c  ces return a NUL
26d70 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 74 68 65  L pointer if the
26d80 79 20 61 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a  y are unable to.
26d90 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  **          allo
26da0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
26db0 6f 6c 64 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c  old their normal
26dc0 20 72 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e   return strings.
26dd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20  .**.** {H13725} 
26de0 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  If the N paramet
26df0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
26e00 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d  olumn_name(S,N)]
26e10 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
26e20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26e30 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20  name16(S,N)] is 
26e40 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
26e50 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
26e60 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
26e70 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  turn a NULL poin
26e80 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ter..**.** {H137
26e90 32 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20  26} The strings 
26ea0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
26eb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26ec0 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  (S,N)] and.**   
26ed0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
26ee0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
26ef0 4e 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e  N)] are valid un
26f00 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20  til the next.** 
26f10 20 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f           call to
26f20 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20   either routine 
26f30 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 53 20  with the same S 
26f40 61 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73  and N parameters
26f50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
26f60 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66  until [sqlite3_f
26f70 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
26f80 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  alled..**.** {H1
26f90 33 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73  3727} When a res
26fa0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  ult column of a 
26fb0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
26fc0 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  nt contains.**  
26fd0 20 20 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c          an AS cl
26fe0 61 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f  ause, the name o
26ff0 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  f that column is
27000 20 74 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a   the identifier.
27010 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
27020 68 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20  he right of the 
27030 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63  AS keyword..*/.c
27040 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
27050 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
27060 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27070 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
27080 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27090 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
270a0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
270b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
270c0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
270d0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
270e0 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30   {H13740} <S1070
270f0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
27100 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
27110 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
27120 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e  mine what column
27130 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c   of what.** tabl
27140 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62  e in which datab
27150 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20  ase a result of 
27160 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
27170 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e  ment comes from.
27180 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
27190 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
271a0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
271b0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
271c0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
271d0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
271e0 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74  tring.  The _dat
271f0 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
27200 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
27210 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
27220 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
27230 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
27240 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
27250 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
27260 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
27270 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
27280 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
27290 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
272a0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
272b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
272c0 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
272d0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
272e0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
272f0 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
27300 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
27310 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
27320 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
27330 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  ng..**.** The na
27340 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
27350 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
27360 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
27370 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
27380 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
27390 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lumn..**.** The 
273a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
273b0 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  o the following 
273c0 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70  calls is a [prep
273d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
273e0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
273f0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
27400 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
27410 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
27420 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
27430 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
27440 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
27450 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
27460 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
27470 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
27480 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
27490 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
274a0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
274b0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
274c0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
274d0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
274e0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
274f0 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65  rn.** NULL.  The
27500 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
27510 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
27520 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
27530 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
27540 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72  * occurs.  Other
27550 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
27560 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
27570 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
27580 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e  ase, table.** an
27590 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  d column that qu
275a0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
275b0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
275c0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77  from..**.** As w
275d0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
275e0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
275f0 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20   postfixed with 
27600 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
27610 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
27620 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72  rings, the other
27630 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
27640 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a  n UTF-8. {END}.*
27650 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20  *.** These APIs 
27660 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
27670 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
27680 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
27690 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
276a0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
276b0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
276c0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
276d0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
276e0 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74  {A13751}.** If t
276f0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
27700 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
27710 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
27720 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
27730 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
27740 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
27750 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
27760 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
27770 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
27780 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
27790 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
277a0 0a 2a 2a 20 7b 48 31 33 37 34 31 7d 20 54 68 65  .** {H13741} The
277b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
277c0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53  _database_name(S
277d0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
277e0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
277f0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
27800 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
27810 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
27820 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68  database from wh
27830 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ich the.**      
27840 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
27850 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
27860 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27870 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64  ] S is extracted
27880 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
27890 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
278a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
278b0 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
278c0 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
278d0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
278e0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
278f0 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
27900 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
27910 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
27920 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
27930 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
27940 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
27950 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
27960 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74    the UTF-16 nat
27970 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a  ive byte order z
27980 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
27990 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
279a0 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ase.**          
279b0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e  from which the N
279c0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
279d0 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
279e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
279f0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
27a00 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
27a10 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
27a20 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
27a30 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
27a40 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
27a50 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
27a60 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
27a70 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
27a80 2a 0a 2a 2a 20 7b 48 31 33 37 34 33 7d 20 54 68  *.** {H13743} Th
27a90 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
27aa0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e  n_table_name(S,N
27ab0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
27ac0 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
27ad0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
27ae0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
27af0 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
27b00 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ble from which t
27b10 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
27b20 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
27b30 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
27b40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
27b50 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20  s extracted,.** 
27b60 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
27b70 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
27b80 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
27b90 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
27ba0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
27bb0 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
27bc0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
27bd0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
27be0 2a 0a 2a 2a 20 7b 48 31 33 37 34 34 7d 20 54 68  *.** {H13744} Th
27bf0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
27c00 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53  n_table_name16(S
27c10 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
27c20 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
27c30 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
27c40 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
27c50 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d   order zero-term
27c60 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
27c70 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  he table.**     
27c80 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20       from which 
27c90 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
27ca0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
27cb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27cc0 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ] S is.**       
27cd0 20 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72     extracted, or
27ce0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
27cf0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
27d00 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
27d10 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
27d20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
27d30 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
27d40 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
27d50 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
27d60 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
27d70 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
27d80 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
27d90 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
27da0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
27db0 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  e UTF-8 zero-ter
27dc0 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
27dd0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
27de0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a   from which the.
27df0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
27e00 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
27e10 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
27e20 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65  tatement] S is e
27e30 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20  xtracted,.**    
27e40 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66        or NULL if
27e50 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
27e60 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
27e70 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  l expression.** 
27e80 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75           or if u
27e90 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
27ea0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72  e memory to stor
27eb0 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
27ec0 2a 20 7b 48 31 33 37 34 36 7d 20 54 68 65 20 5b  * {H13746} The [
27ed0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
27ee0 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e  rigin_name16(S,N
27ef0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
27f00 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
27f10 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
27f20 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
27f30 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  rder zero-termin
27f40 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
27f50 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20   table.**       
27f60 20 20 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77     column from w
27f70 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73  hich the Nth res
27f80 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
27f90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
27fa0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27fb0 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65  t] S is extracte
27fc0 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
27fd0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  e Nth column.** 
27fe0 20 20 20 20 20 20 20 20 20 6f 66 20 53 20 69 73           of S is
27ff0 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65   a general expre
28000 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62  ssion or if unab
28010 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
28020 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
28030 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e    to store the n
28040 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ame..**.** {H137
28050 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  48} The return v
28060 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20  alues from.**   
28070 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
28080 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
28090 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
280a0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
280b0 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  s].**          a
280c0 72 65 20 76 61 6c 69 64 20 66 6f 72 20 74 68 65  re valid for the
280d0 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65   lifetime of the
280e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
280f0 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
28100 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65    or until the e
28110 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67  ncoding is chang
28120 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65  ed by another me
28130 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20  tadata.**       
28140 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c     interface cal
28150 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70  l for the same p
28160 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28170 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  t and column..**
28180 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
28190 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20  .**.** {A13751} 
281a0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
281b0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
281c0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20  or more.**      
281d0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
281e0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
281f0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
28200 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
28210 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
28220 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
28230 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
28240 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
28250 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 20 74  **          at t
28260 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
28270 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
28280 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
28290 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
282a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
282b0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
282c0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
282d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
282e0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
282f0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
28300 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
28310 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28320 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
28330 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28340 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
28350 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28360 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
28370 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
28380 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
28390 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
283a0 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
283b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
283c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
283d0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
283e0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
283f0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
28400 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
28410 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
28420 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
28430 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e  H13760} <S10700>
28440 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
28450 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
28460 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28470 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
28480 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
28490 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
284a0 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
284b0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
284c0 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
284d0 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
284e0 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
284f0 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
28500 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
28510 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
28520 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
28530 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
28540 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
28550 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68  ned.  If the Nth
28560 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
28570 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
28580 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
28590 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
285a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
285b0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54  s returned..** T
285c0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
285d0 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
285e0 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44  -8 encoded. {END
285f0 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  }.**.** For exam
28600 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
28610 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
28620 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
28630 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
28640 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
28650 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
28660 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
28670 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
28680 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
28690 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
286a0 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
286b0 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
286c0 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
286d0 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
286e0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
286f0 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
28700 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
28710 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
28720 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  n (i==0)..**.** 
28730 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
28740 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
28750 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65  ing.  So just be
28760 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
28770 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
28780 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
28790 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
287a0 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
287b0 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
287c0 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
287d0 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
287e0 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
287f0 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
28800 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
28810 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
28820 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79   not static.  Ty
28830 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
28840 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
28850 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
28860 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
28870 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
28880 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
28890 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
288a0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36  TS:.**.** {H1376
288b0 31 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c  1}  A successful
288c0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
288d0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
288e0 65 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20  e(S,N)] returns 
288f0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 7a  a.**           z
28900 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
28910 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74  TF-8 string cont
28920 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61  aining the decla
28930 72 65 64 20 64 61 74 61 74 79 70 65 0a 2a 2a 20  red datatype.** 
28940 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
28950 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
28960 61 74 20 61 70 70 65 61 72 73 20 61 73 20 74 68  at appears as th
28970 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75  e Nth column (nu
28980 6d 62 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  mbered.**       
28990 20 20 20 20 66 72 6f 6d 20 30 29 20 6f 66 20 74      from 0) of t
289a0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f  he result set to
289b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
289c0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
289d0 2a 2a 20 7b 48 31 33 37 36 32 7d 20 20 41 20 73  ** {H13762}  A s
289e0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
289f0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
28a00 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e  n_decltype16(S,N
28a10 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
28a20 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74  returns a zero-t
28a30 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36  erminated UTF-16
28a40 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
28a50 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  er string.**    
28a60 20 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e         containin
28a70 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64  g the declared d
28a80 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74  atatype of the t
28a90 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
28aa0 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20   appears.**     
28ab0 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68        as the Nth
28ac0 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65   column (numbere
28ad0 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65  d from 0) of the
28ae0 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74   result set to t
28af0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  he.**           
28b00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28b10 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ent] S..**.** {H
28b20 31 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20  13763}  If N is 
28b30 6c 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e  less than 0 or N
28b40 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
28b50 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20   or equal to.** 
28b60 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6e 75            the nu
28b70 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
28b80 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
28b90 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a   statement] S,.*
28ba0 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  *           or i
28bb0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
28bc0 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70 72   of S is an expr
28bd0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
28be0 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20  ry rather.**    
28bf0 20 20 20 20 20 20 20 74 68 61 6e 20 61 20 74 61         than a ta
28c00 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69  ble column, or i
28c10 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
28c20 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a  ation failure.**
28c30 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
28c40 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e  s during encodin
28c50 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74  g conversions, t
28c60 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
28c70 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
28c80 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
28c90 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  pe(S,N)] or.**  
28ca0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
28cb0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
28cc0 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e  e16(S,N)] return
28cd0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   NULL..*/.const 
28ce0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
28cf0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
28d00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
28d10 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
28d20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
28d30 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
28d40 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
28d50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
28d60 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
28d70 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20  tement {H13200} 
28d80 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S10000>.**.** A
28d90 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
28da0 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
28db0 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
28dc0 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73  ing either.** [s
28dd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28de0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
28df0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
28e00 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
28e10 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
28e20 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
28e30 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
28e40 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
28e50 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
28e60 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
28e70 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
28e80 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
28e90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
28ea0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
28eb0 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
28ec0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
28ed0 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
28ee0 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
28ef0 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
28f00 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
28f10 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
28f20 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
28f30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
28f40 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
28f50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28f60 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
28f70 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
28f80 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
28f90 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
28fa0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28fb0 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
28fc0 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
28fd0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
28fe0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
28ff0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
29000 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
29010 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
29020 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
29030 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
29040 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  * In the legacy 
29050 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
29060 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
29070 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
29080 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
29090 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
290a0 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
290b0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
290c0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
290d0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69   With the "v2" i
290e0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
290f0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
29100 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
29110 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
29120 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
29130 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
29140 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  l..**.** [SQLITE
29150 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
29160 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
29170 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
29180 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
29190 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
291a0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
291b0 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68   its job.  If th
291c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
291d0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
291e0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
291f0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
29200 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
29210 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
29220 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
29230 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
29240 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
29250 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
29260 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
29270 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
29280 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
29290 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
292a0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
292b0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
292c0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  *.** [SQLITE_DON
292d0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
292e0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
292f0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
29300 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
29310 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
29320 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
29330 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
29340 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
29350 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
29360 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
29370 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29380 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
29390 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
293a0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
293b0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
293c0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
293d0 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
293e0 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
293f0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
29400 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
29410 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
29420 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
29430 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
29440 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
29450 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
29460 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
29470 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
29480 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
29490 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
294a0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
294b0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
294c0 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
294d0 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
294e0 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ta..**.** [SQLIT
294f0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
29500 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
29510 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
29520 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
29530 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
29540 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
29550 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
29560 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
29570 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
29580 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
29590 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
295a0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
295b0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
295c0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
295d0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
295e0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
295f0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
29600 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
29610 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
29620 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
29630 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
29640 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
29650 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
29660 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
29670 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
29680 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
29690 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
296a0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
296b0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
296c0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
296d0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
296e0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
296f0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
29700 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
29710 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
29720 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
29730 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
29740 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
29750 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
29760 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
29770 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
29780 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
29790 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
297a0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
297b0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
297c0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
297d0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
297e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
297f0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
29800 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
29810 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
29820 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
29830 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
29840 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
29850 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
29860 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
29870 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
29880 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
29890 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
298a0 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
298b0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
298c0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
298d0 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
298e0 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
298f0 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
29900 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
29910 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
29920 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
29930 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
29940 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
29950 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
29960 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
29970 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
29980 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
29990 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
299a0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
299b0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
299c0 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
299d0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
299e0 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
299f0 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
29a00 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
29a10 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
29a20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
29a30 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
29a40 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
29a50 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
29a60 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
29a70 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
29a80 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
29a90 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
29aa0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
29ab0 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
29ac0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
29ad0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
29ae0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
29af0 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
29b00 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
29b10 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
29b20 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
29b30 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
29b40 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
29b50 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
29b60 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
29b70 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
29b80 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
29b90 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
29ba0 2a 2a 20 7b 48 31 33 32 30 32 7d 20 20 49 66 20  ** {H13202}  If 
29bb0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
29bc0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65  atement] S is re
29bd0 61 64 79 20 74 6f 20 62 65 20 72 75 6e 2c 20 74  ady to be run, t
29be0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
29bf0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
29c00 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74  )] advances that
29c10 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29c20 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20  ent until.**    
29c30 20 20 20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f         completio
29c40 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73  n or until it is
29c50 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
29c60 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20   another row of 
29c70 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29c80 20 72 65 73 75 6c 74 20 73 65 74 2c 20 6f 72 20   result set, or 
29c90 75 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65  until an [sqlite
29ca0 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e  3_interrupt | in
29cb0 74 65 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20  terrupt].**     
29cc0 20 20 20 20 20 20 6f 72 20 61 20 72 75 6e 2d 74        or a run-t
29cd0 69 6d 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ime error occurs
29ce0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d  ..**.** {H15304}
29cf0 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f    When a call to
29d00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
29d10 29 5d 20 63 61 75 73 65 73 20 74 68 65 20 5b 70  )] causes the [p
29d20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29d30 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  t].**           
29d40 53 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70  S to run to comp
29d50 6c 65 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63  letion, the func
29d60 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51  tion returns [SQ
29d70 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a  LITE_DONE]..**.*
29d80 2a 20 7b 48 31 35 33 30 36 7d 20 20 57 68 65 6e  * {H15306}  When
29d90 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
29da0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74 6f  te3_step(S)] sto
29db0 70 73 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ps because it is
29dc0 20 72 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20   ready to.**    
29dd0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e         return an
29de0 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65  other row of the
29df0 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74 20   result set, it 
29e00 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
29e10 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ROW]..**.** {H15
29e20 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20  308}  If a call 
29e30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
29e40 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20  (S)] encounters 
29e50 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
29e60 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
29e70 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20  pt | interrupt] 
29e80 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  or a run-time er
29e90 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ror,.**         
29ea0 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20    it returns an 
29eb0 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
29ec0 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e  r code that is n
29ed0 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20  ot one of.**    
29ee0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
29ef0 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  K], [SQLITE_ROW]
29f00 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  , or [SQLITE_DON
29f10 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31  E]..**.** {H1531
29f20 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74  0}  If an [sqlit
29f30 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
29f40 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72  nterrupt] or a r
29f50 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a  un-time error.**
29f60 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
29f70 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20  s during a call 
29f80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
29f90 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (S)].**         
29fa0 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65    for a [prepare
29fb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63  d statement] S c
29fc0 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
29fd0 20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79            legacy
29fe0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
29ff0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2a000 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
2a010 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a020 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  16()], then the 
2a030 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
2a040 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
2a050 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
2a060 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  OR], [SQLITE_BUS
2a070 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  Y], or [SQLITE_M
2a080 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ISUSE]..*/.int s
2a090 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
2a0a0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2a0b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2a0c0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2a0d0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b  n a result set {
2a0e0 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e  H13770} <S10700>
2a0f0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74  .**.** Returns t
2a100 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c  he number of val
2a110 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  ues in the curre
2a120 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2a130 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  sult set..**.** 
2a140 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2a150 2a 20 7b 48 31 33 37 37 31 7d 20 20 41 66 74 65  * {H13771}  Afte
2a160 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  r a call to [sql
2a170 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68  ite3_step(S)] th
2a180 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  at returns [SQLI
2a190 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20  TE_ROW],.**     
2a1a0 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
2a1b0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29  e3_data_count(S)
2a1c0 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  ] routine will r
2a1d0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76  eturn the same v
2a1e0 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
2a1f0 20 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65    as the [sqlite
2a200 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53  3_column_count(S
2a210 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  )] function..**.
2a220 2a 2a 20 7b 48 31 33 37 37 32 7d 20 20 41 66 74  ** {H13772}  Aft
2a230 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
2a240 28 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  (S)] has returne
2a250 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  d any value othe
2a260 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  r than.**       
2a270 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d      [SQLITE_ROW]
2a280 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69   or before [sqli
2a290 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
2a2a0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
2a2b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2a2c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a2d0 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69  ment] for the fi
2a2e0 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69  rst time since i
2a2f0 74 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20  t was.**        
2a300 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
2a310 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
2a320 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2a330 74 20 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20  t | reset],.**  
2a340 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
2a350 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2a360 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  (S)] routine ret
2a370 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e  urns zero..*/.in
2a380 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
2a390 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2a3a0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2a3b0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
2a3c0 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
2a3d0 73 20 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31  s {H10265} <S101
2a3e0 31 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b  10><S10120>.** K
2a3f0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
2a400 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  TEXT.**.** {H102
2a410 36 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20  66} Every value 
2a420 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2a430 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2a440 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2a450 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2a460 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2a470 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2a480 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2a490 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2a4a0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2a4b0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2a4c0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2a4d0 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  </ul> {END}.**.*
2a4e0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2a4f0 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
2a500 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
2a510 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
2a520 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
2a530 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
2a540 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
2a550 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
2a560 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
2a570 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
2a580 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
2a590 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
2a5a0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
2a5b0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
2a5c0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2a5d0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
2a5e0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
2a5f0 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
2a600 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2a610 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
2a620 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
2a630 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2a640 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
2a650 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
2a660 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
2a670 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
2a680 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
2a690 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
2a6a0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
2a6b0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
2a6c0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
2a6d0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
2a6e0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
2a6f0 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20  es From A Query 
2a700 7b 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30  {H13800} <S10700
2a710 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
2a720 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2a730 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2a740 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
2a750 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
2a760 65 74 20 71 75 65 72 79 22 20 69 6e 74 65 72 66  et query" interf
2a770 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ace..**.** These
2a780 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2a790 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2a7a0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
2a7b0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
2a7c0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
2a7d0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20  of a query.  In 
2a7e0 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2a7f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2a800 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2a810 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a820 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2a830 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2a840 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2a850 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2a860 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2a870 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a880 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2a890 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2a8a0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2a8b0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2a8c0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2a8d0 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2a8e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2a8f0 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2a900 64 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74  d.  The leftmost
2a910 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2a920 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2a930 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a  e index 0..**.**
2a940 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
2a950 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2a960 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
2a970 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
2a980 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
2a990 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
2a9a0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
2a9b0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2a9c0 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
2a9d0 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
2a9e0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
2a9f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2aa00 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2aa10 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2aa20 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2aa30 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
2aa40 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2aa50 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
2aa60 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
2aa70 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
2aa80 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
2aa90 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
2aaa0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2aab0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
2aac0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2aad0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2aae0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
2aaf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2ab00 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
2ab10 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
2ab20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2ab30 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
2ab40 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2ab50 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
2ab60 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2ab70 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2ab80 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2ab90 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
2aba0 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
2abb0 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
2abc0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2abd0 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
2abe0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
2abf0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2ac00 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
2ac10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2ac20 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
2ac30 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
2ac40 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2ac50 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
2ac60 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
2ac70 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
2ac80 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
2ac90 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
2aca0 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
2acb0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
2acc0 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
2acd0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
2ace0 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
2acf0 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
2ad00 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
2ad10 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2ad20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2ad30 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
2ad40 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
2ad50 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
2ad60 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
2ad70 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
2ad80 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
2ad90 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
2ada0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
2adb0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2adc0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
2add0 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
2ade0 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
2adf0 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
2ae00 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2ae10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ae20 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
2ae30 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
2ae40 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rsion..**.** If 
2ae50 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2ae60 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2ae70 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2ae80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ae90 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2aea0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2aeb0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2aec0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2aed0 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  ng..** If the re
2aee0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
2aef0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2af00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2af10 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
2af20 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2af30 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
2af40 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2af50 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66   of bytes..** If
2af60 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2af70 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2af80 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2af90 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
2afa0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2afb0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2afc0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2afd0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
2afe0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2aff0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2b000 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2b010 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  g..** The value 
2b020 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
2b030 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
2b040 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74  ro terminator at
2b050 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
2b060 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20  he string.  For 
2b070 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
2b080 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74  ue returned is t
2b090 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
2b0a0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2b0b0 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
2b0c0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2b0d0 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73  s..**.** Strings
2b0e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2b0f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2b100 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2b110 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2b120 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2b130 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2b140 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65  s zero terminate
2b150 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a  d.  The return.*
2b160 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
2b170 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2b180 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
2b190 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20  ngth BLOB is an 
2b1a0 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69  arbitrary.** poi
2b1b0 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65  nter, possibly e
2b1c0 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ven a NULL point
2b1d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
2b1e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2b1f0 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69  es16() routine i
2b200 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c  s similar to sql
2b210 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b220 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65  s().** but leave
2b230 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20  s the result in 
2b240 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
2b250 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74   byte order inst
2b260 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a  ead of UTF-8..**
2b270 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   The zero termin
2b280 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c  ator is not incl
2b290 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75  uded in this cou
2b2a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62  nt..**.** The ob
2b2b0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2b2c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2b2d0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
2b2e0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2b2f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2b300 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
2b310 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b320 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
2b330 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2b340 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
2b350 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
2b360 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2b370 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
2b380 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
2b390 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2b3a0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2b3b0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2b3c0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2b3d0 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
2b3e0 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
2b3f0 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
2b400 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2b410 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2b420 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2b430 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2b440 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2b450 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
2b460 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2b470 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2b480 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2b490 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
2b4a0 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
2b4b0 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
2b4c0 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
2b4d0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
2b4e0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
2b4f0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
2b500 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
2b510 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
2b520 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2b530 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
2b540 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
2b550 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
2b560 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2b570 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
2b580 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
2b590 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
2b5a0 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
2b5b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2b5c0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2b5d0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2b5e0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
2b5f0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
2b600 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
2b610 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
2b620 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
2b630 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
2b640 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
2b650 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
2b660 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2b670 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2b680 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
2b690 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2b6a0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2b6b0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2b6c0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2b6d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2b6e0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2b6f0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2b700 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2b710 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2b720 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
2b730 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2b740 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
2b750 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2b760 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2b770 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2b780 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2b790 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
2b7a0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2b7b0 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
2b7c0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
2b7d0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
2b7e0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2b7f0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2b800 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2b810 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
2b820 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2b830 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2b840 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2b850 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2b860 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
2b870 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2b880 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2b890 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
2b8a0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
2b8b0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2b8c0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2b8d0 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
2b8e0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2b8f0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2b900 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
2b910 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2b920 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2b930 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
2b940 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
2b950 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
2b960 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
2b970 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
2b980 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
2b990 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2b9a0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2b9b0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
2b9c0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
2b9d0 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
2b9e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
2b9f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
2ba00 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
2ba10 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
2ba20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2ba30 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
2ba40 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
2ba50 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
2ba60 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
2ba70 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
2ba80 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
2ba90 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
2baa0 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
2bab0 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
2bac0 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
2bad0 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
2bae0 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
2baf0 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
2bb00 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
2bb10 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
2bb20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
2bb30 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
2bb40 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
2bb50 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
2bb60 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
2bb70 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
2bb80 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
2bb90 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
2bba0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
2bbb0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
2bbc0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2bbd0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
2bbe0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
2bbf0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
2bc00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2bc10 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
2bc20 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
2bc30 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
2bc40 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
2bc50 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
2bc60 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
2bc70 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
2bc80 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
2bc90 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2bca0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
2bcb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2bcc0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
2bcd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bce0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2bcf0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
2bd00 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
2bd10 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
2bd20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
2bd30 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
2bd40 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2bd50 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
2bd60 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2bd70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2bd80 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2bd90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2bda0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2bdb0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
2bdc0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
2bdd0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
2bde0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2bdf0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2be00 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
2be10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2be20 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
2be30 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2be40 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
2be50 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2be60 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2be70 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2be80 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
2be90 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e   </ul>.**.** Con
2bea0 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2beb0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2bec0 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2bed0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2bee0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2bef0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2bf00 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2bf10 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2bf20 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2bf30 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2bf40 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70   prior pointer p
2bf50 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61  oints to will ha
2bf60 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
2bf70 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
2bf80 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
2bf90 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
2bfa0 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
2bfb0 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
2bfc0 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
2bfd0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
2bfe0 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
2bff0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
2c000 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
2c010 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
2c020 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
2c030 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
2c040 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
2c050 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2c060 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
2c070 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
2c080 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
2c090 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2c0a0 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
2c0b0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2c0c0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2c0d0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2c0e0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
2c0f0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2c100 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2c110 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2c120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c130 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
2c140 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c150 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
2c160 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2c170 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
2c180 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
2c190 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c1a0 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
2c1b0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
2c1c0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2c1d0 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
2c1e0 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
2c1f0 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
2c200 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
2c210 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
2c220 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c230 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2c240 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c250 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
2c260 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
2c270 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
2c280 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
2c290 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2c2a0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2c2b0 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
2c2c0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2c2d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2c2e0 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
2c2f0 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
2c300 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2c310 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
2c320 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2c330 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
2c340 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20  ** The pointers 
2c350 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
2c360 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
2c370 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
2c380 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
2c390 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
2c3a0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
2c3b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2c3c0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2c3d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2c3e0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  )] is called.  T
2c3f0 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
2c400 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
2c410 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
2c420 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
2c430 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
2c440 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
2c450 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2c460 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
2c470 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
2c480 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c490 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
2c4a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
2c4b0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ree()]..**.** If
2c4c0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2c4d0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2c4e0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2c4f0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2c500 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2c510 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2c520 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2c530 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2c540 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2c550 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2c560 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2c570 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2c580 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2c590 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2c5a0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2c5b0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2c5c0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2c5d0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
2c5e0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2c5f0 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54  **.** {H13803} T
2c600 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2c610 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e  mn_blob(S,N)] in
2c620 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2c630 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c640 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
2c650 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
2c660 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2c670 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
2c680 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2c690 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
2c6a0 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e   a BLOB and then
2c6b0 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20   returns a.**   
2c6c0 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74         pointer t
2c6d0 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20  o the converted 
2c6e0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  value..**.** {H1
2c6f0 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  3806} The [sqlit
2c700 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2c710 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2c720 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
2c730 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
2c740 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 42  f bytes in the B
2c750 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65  LOB or string (e
2c760 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a  xclusive of the.
2c770 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
2c780 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74   terminator on t
2c790 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20  he string) that 
2c7a0 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  was returned by 
2c7b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c7c0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2c7d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
2c7e0 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f  umn_blob(S,N)] o
2c7f0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
2c800 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c810 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20  xt(S,N)]..**.** 
2c820 7b 48 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71  {H13809} The [sq
2c830 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c840 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  es16(S,N)] inter
2c850 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2c860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
2c870 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2c880 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c  the string (excl
2c890 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
2c8a0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
2c8b0 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
2c8c0 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
2c8d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2c8e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
2c8f0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2c900 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c910 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a  _text16(S,N)]..*
2c920 2a 0a 2a 2a 20 7b 48 31 33 38 31 32 7d 20 54 68  *.** {H13812} Th
2c930 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2c940 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69  n_double(S,N)] i
2c950 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2c960 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c970 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
2c980 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
2c990 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2c9a0 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
2c9b0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2c9c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
2c9d0 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  o a floating poi
2c9e0 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20  nt value and.** 
2c9f0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
2ca00 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
2ca10 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  value..**.** {H1
2ca20 33 38 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  3815} The [sqlit
2ca30 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c  e3_column_int(S,
2ca40 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
2ca50 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2ca60 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2ca70 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2ca80 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2ca90 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
2caa0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2cab0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cac0 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  S into a 64-bit 
2cad0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
2cae0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
2caf0 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72  eturns the lower
2cb00 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74   32 bits of that
2cb10 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
2cb20 7b 48 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71  {H13818} The [sq
2cb30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2cb40 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  64(S,N)] interfa
2cb50 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2cb60 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
2cb70 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
2cb80 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2cb90 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20   result set for 
2cba0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2cbb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cbc0 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34  ent] S into a 64
2cbd0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2cbe0 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
2cbf0 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
2cc00 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  py of that integ
2cc10 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32  er..**.** {H1382
2cc20 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
2cc30 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29  column_text(S,N)
2cc40 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2cc50 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2cc60 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
2cc70 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
2cc80 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2cc90 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
2cca0 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72       the [prepar
2ccb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2ccc0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2ccd0 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
2cce0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2ccf0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2cd00 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2cd10 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ring..**.** {H13
2cd20 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  824} The [sqlite
2cd30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2cd40 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2cd50 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2cd60 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
2cd70 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2cd80 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2cd90 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65  sult set for the
2cda0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2cdb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cdc0 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  ] S into a zero-
2cdd0 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74  terminated 2-byt
2cde0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  e.**          al
2cdf0 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74  igned UTF-16 nat
2ce00 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73  ive byte order s
2ce10 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2ce20 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  s.**          a 
2ce30 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2ce40 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
2ce50 31 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  13827} The [sqli
2ce60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2ce70 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2ce80 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
2ce90 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49      one of [SQLI
2cea0 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_NULL], [SQLIT
2ceb0 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
2cec0 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20  ITE_FLOAT],.**  
2ced0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2cee0 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  TEXT], or [SQLIT
2cef0 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
2cf00 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20  priate for.**   
2cf10 20 20 20 20 20 20 20 74 68 65 20 4e 74 68 20 63         the Nth c
2cf20 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
2cf30 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2cf40 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
2cf50 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
2cf60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cf70 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  nt] S..**.** {H1
2cf80 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74  3830} The [sqlit
2cf90 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2cfa0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2cfb0 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20  returns a.**    
2cfc0 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f        pointer to
2cfd0 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
2cfe0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2cff0 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65 0a 2a  object for the.*
2d000 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
2d010 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
2d020 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2d030 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
2d040 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
2d050 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d060 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  nt] S..*/.const 
2d070 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2d080 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
2d090 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d0a0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2d0b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
2d0c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2d0d0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2d0e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2d0f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2d100 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
2d110 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
2d120 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
2d130 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2d140 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2d150 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2d160 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d170 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
2d180 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
2d190 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2d1a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d1b0 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
2d1c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2d1d0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
2d1e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d1f0 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
2d200 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d210 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2d220 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2d230 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2d240 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2d250 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d260 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
2d270 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d280 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2d290 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2d2a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d2b0 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
2d2c0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2d2d0 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53  ject {H13300} <S
2d2e0 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a  70300><S30100>.*
2d2f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2d300 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
2d310 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2d320 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
2d330 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2d340 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74 65  .** If the state
2d350 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65  ment was execute
2d360 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f  d successfully o
2d370 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61  r not executed a
2d380 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53  t all, then.** S
2d390 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
2d3a0 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74 69  rned. If executi
2d3b0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
2d3c0 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20  ent failed then 
2d3d0 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
2d3e0 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
2d3f0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2d400 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
2d410 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
2d420 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2d430 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68   point during th
2d440 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  e execution of t
2d450 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2d460 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20  statement].  If 
2d470 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68  the virtual mach
2d480 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63  ine has not.** c
2d490 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
2d4a0 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  on when this rou
2d4b0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20  tine is called, 
2d4c0 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20  that is like.** 
2d4d0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20  encountering an 
2d4e0 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c  error or an [sql
2d4f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
2d500 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20   interrupt]..** 
2d510 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74  Incomplete updat
2d520 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64  es may be rolled
2d530 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61   back and transa
2d540 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c  ctions canceled,
2d550 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  .** depending on
2d560 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63   the circumstanc
2d570 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b  es, and the.** [
2d580 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75  error code] retu
2d590 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51  rned will be [SQ
2d5a0 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a  LITE_ABORT]..**.
2d5b0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2d5c0 2a 0a 2a 2a 20 7b 48 31 31 33 30 32 7d 20 54 68  *.** {H11302} Th
2d5d0 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  e [sqlite3_final
2d5e0 69 7a 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63  ize(S)] interfac
2d5f0 65 20 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a  e destroys the.*
2d600 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2d610 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d620 53 20 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61  S and releases a
2d630 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ll.**          m
2d640 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72  emory and file r
2d650 65 73 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79  esources held by
2d660 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a   that object..**
2d670 0a 2a 2a 20 7b 48 31 31 33 30 34 7d 20 49 66 20  .** {H11304} If 
2d680 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2d690 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2d6a0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
2d6b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2d6c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d6d0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e  t] S returned an
2d6e0 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20   error,.**      
2d6f0 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
2d700 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72  3_finalize(S)] r
2d710 65 74 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65  eturns that same
2d720 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73   error..*/.int s
2d730 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d740 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2d750 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2d760 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
2d770 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2d780 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33 30  t Object {H13330
2d790 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
2d7a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2d7b0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
2d7c0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
2d7d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2d7e0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2d7f0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
2d800 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
2d810 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
2d820 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c  uted..** Any SQL
2d830 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
2d840 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
2d850 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
2d860 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
2d870 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2d880 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2d890 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
2d8a0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
2d8b0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
2d8c0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
2d8d0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
2d8e0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b  indings..**.** {
2d8f0 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c  H11332} The [sql
2d900 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2d910 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
2d920 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2d930 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20  atement] S.**   
2d940 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74         back to t
2d950 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
2d960 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
2d970 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20 74  ** {H11334} If t
2d980 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2d990 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2d9a0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2d9b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2d9c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d9d0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
2d9e0 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
2d9f0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20  LITE_DONE],.**  
2da00 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73          or if [s
2da10 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2da20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
2da30 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
2da40 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  S,.**          t
2da50 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
2da60 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
2da70 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
2da80 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74 68  * {H11336} If th
2da90 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2daa0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2dab0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2dac0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
2dad0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2dae0 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
2daf0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20  error, then.**  
2db00 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2db10 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
2db20 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
2db30 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
2db40 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54  **.** {H11338} T
2db50 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2db60 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2db70 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
2db80 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20  the values.**   
2db90 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73         of any [s
2dba0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2dbb0 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
2dbc0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2dbd0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
2dbe0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
2dbf0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2dc00 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2dc10 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
2dc20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
2dc30 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20  ctions {H16100} 
2dc40 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S20200>.** KEYW
2dc50 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
2dc60 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2dc70 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
2dc80 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2dc90 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2dca0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
2dcb0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2dcc0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2dcd0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2dce0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  two functions (c
2dcf0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
2dd00 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
2dd10 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2dd20 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
2dd30 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
2dd40 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2dd50 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
2dd60 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2dd70 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
2dd80 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2dd90 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
2dda0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62  nly difference b
2ddb0 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77  etween the.** tw
2ddc0 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65  o is that the se
2ddd0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20  cond parameter, 
2dde0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2ddf0 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f  (scalar) functio
2de00 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2de10 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e  e, is encoded in
2de20 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74   UTF-8 for sqlit
2de30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2de40 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a  on() and UTF-16.
2de50 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
2de60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2de70 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ()..**.** The fi
2de80 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2de90 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2dea0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
2deb0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
2dec0 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
2ded0 20 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69   added.  If a si
2dee0 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65  ngle program use
2def0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
2df00 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2df10 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c  ection internall
2df20 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63  y, then SQL func
2df30 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
2df40 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ded individually
2df50 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61   to.** each data
2df60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
2df70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
2df80 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2df90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
2dfa0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
2dfb0 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
2dfc0 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20  redefined.  The 
2dfd0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
2dfe0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
2dff0 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c   255 bytes, excl
2e000 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20  usive of.** the 
2e010 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
2e020 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
2e030 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69  name length limi
2e040 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e  t is in bytes, n
2e050 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  ot.** characters
2e060 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  .  Any attempt t
2e070 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
2e080 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
2e090 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
2e0a0 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
2e0b0 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65  _ERROR] being re
2e0c0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
2e0d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2e0e0 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
2e0f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2e100 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
2e110 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2e120 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
2e130 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61  es. If this para
2e140 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
2e150 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  e, then the SQL 
2e160 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2e170 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
2e180 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
2e190 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
2e1a0 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
2e1b0 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
2e1c0 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
2e1d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
2e1e0 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
2e1f0 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
2e200 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
2e210 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
2e220 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74  .  Any SQL funct
2e230 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2e240 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c  on should be abl
2e250 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72  e to work.** wor
2e260 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  k with UTF-8, UT
2e270 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
2e280 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
2e290 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
2e2a0 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
2e2b0 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
2e2c0 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
2e2d0 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 61  nother.  It is a
2e2e0 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  llowed to.** inv
2e2f0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
2e300 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
2e310 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2e320 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
2e330 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
2e340 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
2e350 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
2e360 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
2e370 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
2e380 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
2e390 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2e3a0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2e3b0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
2e3c0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
2e3d0 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
2e3e0 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
2e3f0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
2e400 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
2e410 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
2e420 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
2e430 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
2e440 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
2e450 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
2e460 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
2e470 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2e480 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
2e490 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
2e4a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
2e4b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
2e4c0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
2e4d0 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
2e4e0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
2e4f0 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
2e500 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
2e510 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
2e520 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2e530 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  ata()]..**.** Th
2e540 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74  e seventh, eight
2e550 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61  h and ninth para
2e560 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
2e570 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
2e580 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
2e590 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
2e5a0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
2e5b0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
2e5c0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2e5d0 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c  ggregate. A scal
2e5e0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
2e5f0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2e600 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2e610 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
2e620 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70  ack only, NULL p
2e630 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62  ointers should b
2e640 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2e650 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2e660 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
2e670 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
2e680 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2e690 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2e6a0 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
2e6b0 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
2e6c0 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70  NULL should be p
2e6d0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
2e6e0 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78   To delete an ex
2e6f0 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
2e700 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2e710 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66  ate, pass NULL f
2e720 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
2e730 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e  ction callbacks.
2e740 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72  .**.** It is per
2e750 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
2e760 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
2e770 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2e780 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
2e790 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
2e7a0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
2e7b0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
2e7c0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
2e7d0 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
2e7e0 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
2e7f0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
2e800 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73    SQLite will us
2e810 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
2e820 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f  ntation most clo
2e830 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
2e840 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
2e850 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
2e860 6e 20 69 73 20 75 73 65 64 2e 20 20 41 20 66 75  n is used.  A fu
2e870 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2e880 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
2e890 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
2e8a0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
2e8b0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
2e8c0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
2e8d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2e8e0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
2e8f0 6e 41 72 67 2e 20 20 41 20 66 75 6e 63 74 69 6f  nArg.  A functio
2e900 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
2e910 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2e920 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
2e930 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
2e940 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
2e950 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
2e960 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2e970 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
2e980 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
2e990 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
2e9a0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
2e9b0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
2e9c0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
2e9d0 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
2e9e0 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
2e9f0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
2ea00 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2ea10 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
2ea20 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
2ea30 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42  d UTF16..**.** B
2ea40 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
2ea50 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
2ea60 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
2ea70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2ea80 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65  unctions..** The
2ea90 20 66 69 72 73 74 20 61 70 70 6c 69 63 61 74 69   first applicati
2eaa0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2eab0 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e  ion with a given
2eac0 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20   name overrides 
2ead0 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20  all.** built-in 
2eae0 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65  functions in the
2eaf0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
2eb00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68  connection] with
2eb10 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a   the same name..
2eb20 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 70  ** Subsequent ap
2eb30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2eb40 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74  d functions of t
2eb50 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c  he same name onl
2eb60 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70  y override .** p
2eb70 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  rior application
2eb80 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2eb90 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 65  ns that are an e
2eba0 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74  xact match for t
2ebb0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2ebc0 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70  parameters and p
2ebd0 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e  referred encodin
2ebe0 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c  g..**.** An appl
2ebf0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2ec00 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
2ec10 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
2ec20 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
2ec30 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
2ec40 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
2ec50 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
2ec60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2ec70 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
2ec80 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
2ec90 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
2eca0 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
2ecb0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
2ecc0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
2ecd0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2ece0 2a 2a 20 7b 48 31 36 31 30 33 7d 20 54 68 65 20  ** {H16103} The 
2ecf0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ed00 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 2e  function16(D,X,.
2ed10 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  ..)] interface s
2ed20 68 61 6c 6c 20 62 65 68 61 76 65 0a 2a 2a 20 20  hall behave.**  
2ed30 20 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69          as [sqli
2ed40 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ed50 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e  ion(D,X,...)] in
2ed60 20 65 76 65 72 79 20 77 61 79 20 65 78 63 65 70   every way excep
2ed70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20 20 20  t that it.**    
2ed80 20 20 20 20 20 20 69 6e 74 65 72 70 72 65 74 73        interprets
2ed90 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20   the X argument 
2eda0 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  as zero-terminat
2edb0 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20  ed UTF-16.**    
2edc0 20 20 20 20 20 20 6e 61 74 69 76 65 20 62 79 74        native byt
2edd0 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20  e order instead 
2ede0 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69  of as zero-termi
2edf0 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a  nated UTF-8..**.
2ee00 2a 2a 20 7b 48 31 36 31 30 36 7d 20 41 20 73 75  ** {H16106} A su
2ee10 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
2ee20 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ion of the.**   
2ee30 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2ee40 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2ee50 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e  D,X,N,E,...)] in
2ee60 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65  terface shall re
2ee70 67 69 73 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  gister.**       
2ee80 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63     or replaces c
2ee90 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2eea0 73 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61  s in the [databa
2eeb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2eec0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65  .**          use
2eed0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  d to implement t
2eee0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2eef0 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70  named X with N p
2ef00 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20  arameters.**    
2ef10 20 20 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67        and having
2ef20 20 61 20 70 72 65 66 65 72 72 65 64 20 74 65 78   a preferred tex
2ef30 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e  t encoding of E.
2ef40 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 39 7d 20  .**.** {H16109} 
2ef50 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
2ef60 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  l to [sqlite3_cr
2ef70 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2ef80 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a  X,N,E,P,F,S,L)].
2ef90 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
2efa0 6c 20 72 65 70 6c 61 63 65 20 74 68 65 20 50 2c  l replace the P,
2efb0 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c   F, S, and L val
2efc0 75 65 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69  ues from any pri
2efd0 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a  or calls with.**
2efe0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
2eff0 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20  me D, X, N, and 
2f000 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20  E values..**.** 
2f010 7b 48 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71  {H16112} The [sq
2f020 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f030 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20  ction(D,X,...)] 
2f040 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2f050 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  fail.**         
2f060 20 69 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   if the SQL func
2f070 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a  tion name X is.*
2f080 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65  *          longe
2f090 72 20 74 68 61 6e 20 32 35 35 20 62 79 74 65 73  r than 255 bytes
2f0a0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
2f0b0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
2f0c0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 38  r..**.** {H16118
2f0d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2f0e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2f0f0 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
2f100 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20   interface.**   
2f110 20 20 20 20 20 20 20 73 68 61 6c 6c 20 66 61 69         shall fai
2f120 6c 20 75 6e 6c 65 73 73 20 65 69 74 68 65 72 20  l unless either 
2f130 46 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 53 20  F is NULL and S 
2f140 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55  and L are non-NU
2f150 4c 4c 20 6f 72 0a 2a 2a 2a 20 20 20 20 20 20 20  LL or.***       
2f160 20 20 46 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20    F is non-NULL 
2f170 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20  and S and L are 
2f180 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  NULL..**.** {H16
2f190 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  121} The [sqlite
2f1a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f1b0 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  n(D,...)] interf
2f1c0 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c 73 20  ace shall fails 
2f1d0 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
2f1e0 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f      error code o
2f1f0 66 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  f [SQLITE_BUSY] 
2f200 69 66 20 74 68 65 72 65 20 65 78 69 73 74 20 5b  if there exist [
2f210 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f220 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  nts].**         
2f230 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2f240 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2f250 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
2f260 0a 2a 2a 20 7b 48 31 36 31 32 34 7d 20 54 68 65  .** {H16124} The
2f270 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f280 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2f290 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
2f2a0 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 0a  shall fail with.
2f2b0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 65  **          an e
2f2c0 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
2f2d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70  LITE_ERROR] if p
2f2e0 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 6c 65  arameter N is le
2f2f0 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ss.**          t
2f300 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
2f310 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a  r than 127..**.*
2f320 2a 20 7b 48 31 36 31 32 37 7d 20 57 68 65 6e 20  * {H16127} When 
2f330 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
2f340 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  e, the [sqlite3_
2f350 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2f360 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  D,X,N,...)].**  
2f370 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
2f380 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74 65 72  e shall register
2f390 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65   callbacks to be
2f3a0 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65   invoked for the
2f3b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
2f3c0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2f3d0 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 68        named X wh
2f3e0 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  en the number of
2f3f0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
2f400 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2f410 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
2f420 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  actly N..**.** {
2f430 48 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20 69  H16130} When N i
2f440 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69 74  s -1, the [sqlit
2f450 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f460 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a  on(D,X,N,...)].*
2f470 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
2f480 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73  face shall regis
2f490 74 65 72 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f  ter callbacks to
2f4a0 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   be invoked for 
2f4b0 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20  the SQL.**      
2f4c0 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d      function nam
2f4d0 65 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e 75  ed X with any nu
2f4e0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2f4f0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 33  s..**.** {H16133
2f500 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  } When calls to 
2f510 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f520 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
2f530 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
2f540 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c   specify multipl
2f550 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f560 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2f570 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20  nction X.**     
2f580 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e       and when on
2f590 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f5a0 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68   has N>=0 and th
2f5b0 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28 2d  e other has N=(-
2f5c0 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  1).**          t
2f5d0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2f5e0 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  n with a non-zer
2f5f0 6f 20 4e 20 73 68 61 6c 6c 20 62 65 20 70 72 65  o N shall be pre
2f600 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ferred..**.** {H
2f610 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c  16136} When call
2f620 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  s to [sqlite3_cr
2f630 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2f640 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  X,N,E,...)].**  
2f650 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79 20          specify 
2f660 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2f670 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2f680 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20  same function X 
2f690 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
2f6a0 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72   the same number
2f6b0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20   of arguments N 
2f6c0 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
2f6d0 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  nt.**          e
2f6e0 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e  ncodings E, then
2f6f0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2f700 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63  ion where E matc
2f710 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  hes the.**      
2f720 20 20 20 20 64 61 74 61 62 61 73 65 20 65 6e 63      database enc
2f730 6f 64 69 6e 67 20 73 68 61 6c 6c 20 70 72 65 66  oding shall pref
2f740 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  erred..**.** {H1
2f750 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67  6139} For an agg
2f760 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2f770 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e  ion created usin
2f780 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
2f790 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f7a0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
2f7b0 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e  ,0,S,L)] the fin
2f7c0 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20  alizer.**       
2f7d0 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 73 68     function L sh
2f7e0 61 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e  all always be in
2f7f0 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  voked exactly on
2f800 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  ce if the.**    
2f810 20 20 20 20 20 20 73 74 65 70 20 66 75 6e 63 74        step funct
2f820 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20  ion S is called 
2f830 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
2f840 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34 32  s..**.** {H16142
2f850 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  } When SQLite in
2f860 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68 65  vokes either the
2f870 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20   xFunc or xStep 
2f880 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20  function of.**  
2f890 20 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69          an appli
2f8a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2f8b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
2f8c0 67 67 72 65 67 61 74 65 20 63 72 65 61 74 65 64  ggregate created
2f8d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
2f8e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f8f0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b  function()] or [
2f900 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f910 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a  unction16()],.**
2f920 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
2f930 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c  he array of [sql
2f940 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2f950 63 74 73 20 70 61 73 73 65 64 20 61 73 20 74 68  cts passed as th
2f960 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
2f970 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 68  ird parameter sh
2f980 61 6c 6c 20 62 65 20 5b 70 72 6f 74 65 63 74 65  all be [protecte
2f990 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2f9a0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74   objects..*/.int
2f9b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2f9c0 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
2f9d0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2f9e0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2f9f0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2fa00 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2fa10 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2fa20 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2fa30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fa40 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2fa50 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2fa60 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2fa70 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2fa80 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2fa90 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2faa0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2fab0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2fac0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2fad0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2fae0 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
2faf0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2fb00 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2fb10 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2fb20 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2fb30 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2fb40 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2fb50 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2fb60 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2fb70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fb80 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2fb90 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2fba0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2fbb0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a  context*).);../*
2fbc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2fbd0 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31  xt Encodings {H1
2fbe0 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c  0267} <S50200> <
2fbf0 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H16100>.**.** Th
2fc00 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
2fc10 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
2fc20 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
2fc30 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
2fc40 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
2fc50 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
2fc60 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
2fc70 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
2fc80 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
2fc90 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
2fca0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
2fcb0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
2fcc0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
2fcd0 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
2fce0 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
2fcf0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2fd00 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
2fd10 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
2fd20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
2fd30 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2fd40 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
2fd50 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2fd60 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
2fd70 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2fd80 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
2fd90 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
2fda0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
2fdb0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
2fdc0 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
2fdd0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
2fde0 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
2fdf0 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
2fe00 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
2fe10 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
2fe20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
2fe30 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2fe40 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
2fe50 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
2fe60 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
2fe70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2fe80 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
2fe90 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
2fea0 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
2feb0 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
2fec0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
2fed0 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
2fee0 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
2fef0 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
2ff00 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
2ff10 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
2ff20 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
2ff30 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2ff40 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
2ff50 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
2ff60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2ff70 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2ff80 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
2ff90 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
2ffa0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
2ffb0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2ffc0 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
2ffd0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2ffe0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
2fff0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
30000 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
30010 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
30020 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
30030 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
30040 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
30050 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
30060 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
30070 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
30080 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
30090 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
300a0 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a  int64,int),void*
300b0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
300c0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
300d0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
300e0 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
300f0 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
30100 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30   {H15100} <S2020
30110 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  0>.**.** The C-l
30120 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
30130 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
30140 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
30150 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
30160 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
30170 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
30180 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
30190 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
301a0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
301b0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
301c0 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
301d0 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
301e0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
301f0 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
30200 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
30210 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
30220 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
30230 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
30240 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
30250 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
30260 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
30270 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30280 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
30290 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61  s..** The 4th pa
302a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
302b0 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
302c0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
302d0 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
302e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
302f0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
30300 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
30310 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30320 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
30330 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
30340 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
30350 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
30360 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
30370 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
30380 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30390 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
303a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
303b0 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
303c0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
303d0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
303e0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
303f0 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
30400 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
30410 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
30420 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
30430 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
30440 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
30450 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  r..**.** These r
30460 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
30470 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
30480 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
30490 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
304a0 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
304b0 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
304c0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
304d0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
304e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
304f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
30500 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
30510 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
30520 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
30530 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
30540 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30550 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
30560 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
30570 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
30580 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
30590 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
305a0 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
305b0 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ne.  The.** sqli
305c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
305d0 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
305e0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
305f0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
30600 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
30610 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
30620 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
30630 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
30640 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
30650 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
30660 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
30670 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
30680 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
30690 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
306a0 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
306b0 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
306c0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
306d0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
306e0 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
306f0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
30700 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
30710 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
30720 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
30730 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
30740 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
30750 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
30760 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
30770 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
30780 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
30790 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
307a0 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
307b0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
307c0 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
307d0 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
307e0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
307f0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
30800 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
30810 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  rned..**.** Plea
30820 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
30830 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
30840 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
30850 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
30860 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
30870 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
30880 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
30890 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
308a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
308b0 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
308c0 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
308d0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
308e0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
308f0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
30900 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
30910 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
30920 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
30930 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
30940 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
30950 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
30960 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
30970 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
30980 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
30990 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
309a0 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
309b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
309c0 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
309d0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
309e0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30  TS:.**.** {H1510
309f0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
30a00 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69  value_blob(V)] i
30a10 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
30a20 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
30a30 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
30a40 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30a50 63 74 20 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42  ct V into a BLOB
30a60 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20   and then.**    
30a70 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
30a80 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
30a90 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a  onverted value..
30aa0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54  **.** {H15106} T
30ab0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30ac0 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e 74 65  e_bytes(V)] inte
30ad0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
30ae0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
30af0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
30b00 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
30b10 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
30b20 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
30b30 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
30b40 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
30b50 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
30b60 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
30b70 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
30b80 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
30b90 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29  e3_value_blob(V)
30ba0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
30bb0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30bc0 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20  text(V)]..**.** 
30bd0 7b 48 31 35 31 30 39 7d 20 54 68 65 20 5b 73 71  {H15109} The [sq
30be0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
30bf0 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63  s16(V)] interfac
30c00 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
30c10 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
30c20 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
30c30 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
30c40 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
30c50 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
30c60 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
30c70 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
30c80 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
30c90 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
30ca0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
30cb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30cc0 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20  t16(V)],.**     
30cd0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61       [sqlite3_va
30ce0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d  lue_text16be(V)]
30cf0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  , or [sqlite3_va
30d00 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d  lue_text16le(V)]
30d10 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d  ..**.** {H15112}
30d20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
30d30 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69  lue_double(V)] i
30d40 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
30d50 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
30d60 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
30d70 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30d80 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61  ct V into a floa
30d90 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
30da0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
30db0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
30dc0 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a  of that value..*
30dd0 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d 20 54 68  *.** {H15115} Th
30de0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
30df0 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66 61  _int(V)] interfa
30e00 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
30e10 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
30e20 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30e30 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
30e40 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
30e50 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
30e60 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
30e70 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32  rns the lower 32
30e80 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e   bits of that in
30e90 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  teger..**.** {H1
30ea0 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  5118} The [sqlit
30eb0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 56  e3_value_int64(V
30ec0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
30ed0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
30ee0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
30ef0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
30f00 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
30f10 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
30f20 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
30f30 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
30f40 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74  copy of that int
30f50 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  eger..**.** {H15
30f60 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  121} The [sqlite
30f70 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d  3_value_text(V)]
30f80 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
30f90 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
30fa0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
30fb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30fc0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
30fd0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
30fe0 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F-8.**          
30ff0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
31000 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
31010 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
31020 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54 68 65 20  ** {H15124} The 
31030 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
31040 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65 72 66  ext16(V)] interf
31050 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
31060 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
31070 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
31080 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
31090 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
310a0 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
310b0 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
310c0 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
310d0 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
310e0 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
310f0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
31100 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
31110 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32  ng..**.** {H1512
31120 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
31130 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56  value_text16be(V
31140 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
31150 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
31160 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
31170 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
31180 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
31190 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
311a0 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
311b0 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
311c0 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20  6 big-endian.** 
311d0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
311e0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
311f0 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
31200 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
31210 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  130} The [sqlite
31220 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
31230 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
31240 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
31250 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
31260 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31270 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
31280 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
31290 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
312a0 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
312b0 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
312c0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
312d0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
312e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
312f0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
31300 20 7b 48 31 35 31 33 33 7d 20 54 68 65 20 5b 73   {H15133} The [s
31310 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
31320 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
31330 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
31340 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49      one of [SQLI
31350 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_NULL], [SQLIT
31360 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
31370 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20  ITE_FLOAT],.**  
31380 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
31390 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  TEXT], or [SQLIT
313a0 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
313b0 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20  priate for.**   
313c0 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
313d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
313e0 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  t V..**.** {H151
313f0 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
31400 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
31410 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ype(V)] interfac
31420 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20  e converts.**   
31430 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74         the [prot
31440 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
31450 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
31460 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69 6e 74  to either an int
31470 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20  eger or.**      
31480 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67 20 70      a floating p
31490 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20 69 74  oint value if it
314a0 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f   can do so witho
314b0 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20  ut loss of.**   
314c0 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69         informati
314d0 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  on, and returns 
314e0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
314f0 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ULL],.**        
31500 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45    [SQLITE_INTEGE
31510 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
31520 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
31530 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
31540 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20    [SQLITE_BLOB] 
31550 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
31560 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
31570 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
31580 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31590 65 63 74 20 56 20 61 66 74 65 72 20 74 68 65 20  ect V after the 
315a0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74 65 6d  conversion attem
315b0 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  pt..*/.const voi
315c0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
315d0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
315e0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
315f0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
31600 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31610 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
31620 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
31630 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
31640 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
31650 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
31660 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
31670 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
31680 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
31690 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
316a0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
316b0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
316c0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
316d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
316e0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
316f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
31700 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
31710 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
31720 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
31730 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31740 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
31750 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31760 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
31770 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
31780 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
31790 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
317a0 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
317b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
317c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
317d0 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
317e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
317f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
31800 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
31810 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
31820 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30  {H16210} <S20200
31830 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  >.**.** The impl
31840 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
31850 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
31860 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
31870 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
31880 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
31890 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
318a0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
318b0 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
318c0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
318d0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
318e0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
318f0 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69  d for a.** parti
31900 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
31910 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65   SQLite allocate
31920 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f  s nBytes of memo
31930 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
31940 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61  hat.** memory, a
31950 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
31960 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73  nter to it. On s
31970 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
31980 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
31990 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
319a0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
319b0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
319c0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
319d0 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ex,.** the same 
319e0 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
319f0 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ed. The implemen
31a00 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67  tation of the ag
31a10 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a  gregate can use.
31a20 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  ** the returned 
31a30 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
31a40 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
31a50 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
31a60 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
31a70 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72  allocated buffer
31a80 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
31a90 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e  ate.** query con
31aa0 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
31ab0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
31ac0 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f  r should be a co
31ad0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
31ae0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
31af0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
31b00 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
31b10 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
31b20 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
31b30 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
31b40 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
31b50 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
31b60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
31b70 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
31b80 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
31b90 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
31ba0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
31bb0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
31bc0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
31bd0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
31be0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20  .**.** {H16211} 
31bf0 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61  The first invoca
31c00 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
31c10 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31c20 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20  xt(C,N)] for.** 
31c30 20 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69           a parti
31c40 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f  cular instance o
31c50 66 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66  f an aggregate f
31c60 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70  unction (for a p
31c70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20  articular.**    
31c80 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29        context C)
31c90 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
31ca0 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74  o allocate N byt
31cb0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  es of memory,.**
31cc0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
31cd0 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
31ce0 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
31cf0 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   to the allocate
31d00 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  d memory..**.** 
31d10 7b 48 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65  {H16213} If a me
31d20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
31d30 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
31d40 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
31d50 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
31d60 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
31d70 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
31d80 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  on returns 0..**
31d90 0a 2a 2a 20 7b 48 31 36 32 31 35 7d 20 53 65 63  .** {H16215} Sec
31da0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
31db0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
31dc0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
31dd0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31de0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66  _context(C,N)] f
31df0 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74  or the same cont
31e00 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a  ext pointer C.**
31e10 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65            ignore
31e20 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
31e30 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
31e40 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d  inter to the sam
31e50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c  e.**          bl
31e60 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65  ock of memory re
31e70 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69  turned by the fi
31e80 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  rst invocation..
31e90 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54  **.** {H16217} T
31ea0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
31eb0 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
31ec0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31ed0 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20  t(C,N)] is.**   
31ee0 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63         automatic
31ef0 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68  ally freed on th
31f00 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b  e next call to [
31f10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
31f20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
31f30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31f40 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72  e()] for the [pr
31f50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31f60 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20  ] containing.** 
31f70 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67           the agg
31f80 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
31f90 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
31fa0 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f  context C..*/.vo
31fb0 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
31fc0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
31fd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31fe0 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
31ff0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
32000 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
32010 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c  tions {H16240} <
32020 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
32030 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
32040 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
32050 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
32060 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
32070 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
32080 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
32090 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
320a0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
320b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
320c0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
320d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
320e0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
320f0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
32100 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
32110 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
32120 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
32130 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
32140 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
32150 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
32160 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
32170 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
32180 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
32190 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
321a0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
321b0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
321c0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d  :.**.** {H16243}
321d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73   The [sqlite3_us
321e0 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65  er_data(C)] inte
321f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
32200 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
32210 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65          P pointe
32220 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  r from the [sqli
32230 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32240 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
32250 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
32260 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72    or [sqlite3_cr
32270 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
32280 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
32290 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20  ] call that.**  
322a0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
322b0 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ed the SQL funct
322c0 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
322d0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ith [sqlite3_con
322e0 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64  text] C..*/.void
322f0 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
32300 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
32310 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
32320 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
32330 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
32340 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35  Functions {H1625
32350 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32  0} <S60600><S202
32360 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
32370 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
32380 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
32390 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
323a0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
323b0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
323c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
323d0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
323e0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
323f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32400 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
32410 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
32420 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
32430 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
32440 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
32450 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
32460 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
32470 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
32480 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
32490 2a 20 7b 48 31 36 32 35 33 7d 20 54 68 65 20 5b  * {H16253} The [
324a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
324b0 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e  db_handle(C)] in
324c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
324d0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
324e0 20 20 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e            D poin
324f0 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ter from the [sq
32500 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32510 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
32520 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
32530 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
32540 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
32550 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  6(D,X,N,E,P,F,S,
32560 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a  L)] call that.**
32570 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
32580 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e  ered the SQL fun
32590 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64  ction associated
325a0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63   with [sqlite3_c
325b0 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71  ontext] C..*/.sq
325c0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
325d0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
325e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
325f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
32600 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
32610 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31  xiliary Data {H1
32620 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6270} <S20200>.*
32630 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
32640 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
32650 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
32660 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
32670 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
32680 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
32690 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
326a0 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
326b0 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
326c0 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
326d0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
326e0 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
326f0 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
32700 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
32710 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
32720 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
32730 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
32740 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
32750 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
32760 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
32770 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
32780 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
32790 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
327a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
327b0 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
327c0 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
327d0 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
327e0 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
327f0 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
32800 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
32810 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
32820 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
32830 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
32840 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
32850 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
32860 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
32870 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
32880 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
32890 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
328a0 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
328b0 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
328c0 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
328d0 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
328e0 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
328f0 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ocation..**.** T
32900 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
32910 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
32920 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
32930 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
32940 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
32950 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
32960 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
32970 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
32980 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
32990 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
329a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
329b0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20  ed function. If 
329c0 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
329d0 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
329e0 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
329f0 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
32a00 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
32a10 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
32a20 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
32a30 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
32a40 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
32a50 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
32a60 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
32a70 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
32a80 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
32a90 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
32aa0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
32ab0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
32ac0 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
32ad0 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
32ae0 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
32af0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
32b00 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
32b10 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
32b20 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
32b30 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32b40 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
32b50 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
32b60 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
32b70 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
32b80 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
32b90 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
32ba0 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
32bb0 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55   If it is not NU
32bc0 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
32bd0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
32be0 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
32bf0 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
32c00 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
32c10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32c20 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
32c30 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
32c40 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
32c50 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
32c60 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
32c70 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
32c80 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
32c90 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
32ca0 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
32cb0 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
32cc0 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
32cd0 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
32ce0 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
32cf0 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
32d00 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
32d10 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e  ny time.  The on
32d20 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
32d30 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
32d40 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
32d50 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
32d60 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
32d70 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70  pped..**.** In p
32d80 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
32d90 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
32da0 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
32db0 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
32dc0 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
32dd0 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
32de0 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
32df0 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
32e00 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
32e10 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a  SQL variables..*
32e20 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
32e30 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
32e40 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
32e50 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
32e60 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
32e70 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
32e80 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
32e90 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32  S:.**.** {H16272
32ea0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
32eb0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d  et_auxdata(C,N)]
32ec0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
32ed0 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
32ee0 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61           to meta
32ef0 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
32f00 77 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72  with the Nth par
32f10 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51  ameter of the SQ
32f20 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
32f30 20 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e         whose con
32f40 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55  text is C, or NU
32f50 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e  LL if there is n
32f60 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  o metadata assoc
32f70 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  iated.**        
32f80 20 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61    with that para
32f90 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  meter..**.** {H1
32fa0 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6274} The [sqlit
32fb0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
32fc0 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,N,P,D)] interfa
32fd0 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74  ce assigns a met
32fe0 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20  adata.**        
32ff0 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74    pointer P to t
33000 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72  he Nth parameter
33010 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
33020 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78  tion with contex
33030 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  t C..**.** {H162
33040 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  76} SQLite will 
33050 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
33060 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73  uctor D with a s
33070 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ingle argument.*
33080 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68  *          which
33090 20 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   is the metadata
330a0 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f   pointer P follo
330b0 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  wing a call to.*
330c0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
330d0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
330e0 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53  C,N,P,D)] when S
330f0 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20  QLite ceases to 
33100 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  hold.**         
33110 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a   the metadata..*
33120 2a 0a 2a 2a 20 7b 48 31 36 32 37 37 7d 20 53 51  *.** {H16277} SQ
33130 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68  Lite ceases to h
33140 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72  old metadata for
33150 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
33160 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
33170 20 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20         when the 
33180 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61  value of that pa
33190 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e  rameter changes.
331a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20  .**.** {H16278} 
331b0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65  When [sqlite3_se
331c0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
331d0 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  D)] is invoked, 
331e0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
331f0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61  *          is ca
33200 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69  lled for any pri
33210 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  or metadata asso
33220 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
33230 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
33240 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
33250 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65  t C and paramete
33260 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  r N..**.** {H162
33270 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  79} SQLite will 
33280 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73  call destructors
33290 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74   for any metadat
332a0 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a  a it is holding.
332b0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61  **          in a
332c0 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65   particular [pre
332d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
332e0 20 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a   S when either.*
332f0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
33300 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72  te3_reset(S)] or
33310 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
33320 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
33330 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
33340 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
33350 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33360 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
33370 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33380 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
33390 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
333a0 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
333b0 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
333c0 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
333d0 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
333e0 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
333f0 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c 53  vior {H10280} <S
33400 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30100>.**.** The
33410 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
33420 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
33430 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
33440 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
33450 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
33460 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
33470 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
33480 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49  sult_blob()].  I
33490 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
334a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
334b0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
334c0 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
334d0 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
334e0 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
334f0 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
33500 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
33510 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
33520 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a  estroyed.  The.*
33530 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
33540 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
33550 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
33560 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
33570 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
33580 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
33590 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
335a0 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
335b0 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
335c0 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
335d0 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
335e0 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
335f0 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
33600 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
33610 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
33620 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
33630 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
33640 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  191..*/.typedef 
33650 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
33660 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
33670 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
33680 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
33690 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
336a0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
336b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
336c0 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
336d0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
336e0 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
336f0 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
33700 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
33710 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  An SQL Function 
33720 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32 30 30  {H16400} <S20200
33730 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
33740 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
33750 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
33760 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
33770 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
33780 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
33790 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
337a0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
337b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
337c0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
337d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
337e0 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
337f0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
33800 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
33810 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
33820 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
33830 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
33840 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
33850 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
33860 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
33870 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
33880 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
33890 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
338a0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
338b0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
338c0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
338d0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
338e0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
338f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33900 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
33910 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
33920 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
33930 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33940 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
33950 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
33960 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
33970 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
33980 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
33990 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
339a0 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
339b0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
339c0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
339d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
339e0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
339f0 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
33a00 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
33a10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33a20 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
33a30 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
33a40 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
33a50 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
33a60 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
33a70 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
33a80 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
33a90 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
33aa0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
33ab0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
33ac0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
33ad0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
33ae0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
33af0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
33b00 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
33b10 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
33b20 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
33b30 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
33b40 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
33b50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
33b60 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
33b70 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
33b80 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
33b90 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
33ba0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
33bb0 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
33bc0 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  on..** SQLite us
33bd0 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
33be0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
33bf0 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
33c00 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
33c10 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
33c20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33c30 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
33c40 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
33c50 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69  r message.  SQLi
33c60 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
33c70 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
33c80 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
33c90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33ca0 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
33cb0 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
33cc0 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
33cd0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
33ce0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
33cf0 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
33d00 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
33d10 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70    If the third p
33d20 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
33d30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33d40 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
33d50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33d60 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
33d70 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
33d80 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
33d90 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
33da0 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
33db0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
33dc0 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cter..** If the 
33dd0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
33de0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
33df0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
33e00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33e10 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
33e20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
33e30 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
33e40 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
33e50 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
33e60 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
33e70 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
33e80 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54  or message..** T
33e90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33ea0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
33eb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33ec0 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
33ed0 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
33ee0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
33ef0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
33f00 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
33f10 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
33f20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
33f30 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
33f40 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
33f50 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
33f60 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
33f70 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65  out harm..** The
33f80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33f90 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
33fa0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
33fb0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
33fc0 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
33fd0 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
33fe0 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
33ff0 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65  function.  By de
34000 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
34010 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
34020 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62  TE_ERROR.  A sub
34030 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
34040 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34050 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
34060 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34070 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
34080 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
34090 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
340a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
340b0 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69  esult_toobig() i
340c0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
340d0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
340e0 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
340f0 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
34100 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
34110 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  to long to repre
34120 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  sent..**.** The 
34130 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
34140 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
34150 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
34160 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
34170 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
34180 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
34190 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
341a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
341b0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
341c0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
341d0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
341e0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
341f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34200 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
34210 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
34220 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
34230 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
34240 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
34250 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34260 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
34270 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
34280 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
34290 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
342a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
342b0 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
342c0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
342d0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
342e0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
342f0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
34300 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
34310 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
34320 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
34330 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
34340 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34350 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
34360 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
34370 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34380 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
34390 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
343a0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
343b0 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
343c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
343d0 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
343e0 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
343f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
34400 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
34410 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34420 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
34430 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
34440 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
34450 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
34460 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
34470 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
34480 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
34490 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
344a0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
344b0 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  ** SQLite takes 
344c0 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
344d0 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
344e0 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
344f0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
34500 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
34510 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
34520 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  faces..** If the
34530 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
34540 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
34550 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
34560 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
34570 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
34580 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
34590 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
345a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
345b0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
345c0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
345d0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
345e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
345f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34600 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
34610 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
34620 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
34630 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
34640 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
34650 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
34660 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
34670 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
34680 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
34690 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
346a0 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a  nction result..*
346b0 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
346c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
346d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
346e0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
346f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
34700 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
34710 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
34720 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
34730 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
34740 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
34750 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
34760 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
34770 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
34780 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
34790 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  t result..** If 
347a0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
347b0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
347c0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
347d0 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73  terfaces or.** s
347e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
347f0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
34800 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
34810 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
34820 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
34830 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
34840 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
34850 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
34860 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
34870 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74 20 6f  ** copy the it o
34880 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
34890 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61 73 20  tor when it has 
348a0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
348b0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
348c0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
348d0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
348e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
348f0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
34900 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34910 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
34920 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
34930 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
34940 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
34950 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
34960 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
34970 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
34980 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
34990 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
349a0 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
349b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
349c0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
349d0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
349e0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
349f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34a00 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34a10 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
34a20 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
34a30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34a40 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
34a50 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
34a60 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20  ameter.  The.** 
34a70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34a80 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
34a90 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
34aa0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
34ab0 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
34ac0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
34ad0 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
34ae0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
34af0 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
34b00 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
34b10 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
34b20 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
34b30 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
34b40 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65  ..** A [protecte
34b50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34b60 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
34b70 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
34b80 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
34b90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34ba0 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
34bb0 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
34bc0 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
34bd0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34be0 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
34bf0 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
34c00 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
34c10 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
34c20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
34c30 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
34c40 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
34c50 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
34c60 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
34c70 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34c80 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
34c90 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
34ca0 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
34cb0 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
34cc0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
34cd0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
34ce0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20  .**.** {H16403} 
34cf0 54 68 65 20 64 65 66 61 75 6c 74 20 72 65 74 75  The default retu
34d00 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  rn value from an
34d10 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
34d20 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  s NULL..**.** {H
34d30 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  16406} The [sqli
34d40 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
34d50 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
34d60 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
34d70 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
34d80 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
34d90 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 42  tion C to be a B
34da0 4c 4f 42 20 74 68 61 74 20 69 73 20 4e 20 62 79  LOB that is N by
34db0 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
34dc0 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69  in length and wi
34dd0 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  th content point
34de0 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a  ed to by V..**.*
34df0 2a 20 7b 48 31 36 34 30 39 7d 20 54 68 65 20 5b  * {H16409} The [
34e00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
34e10 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65  ouble(C,V)] inte
34e20 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
34e30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
34e40 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
34e50 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
34e60 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
34e70 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  t value V..**.**
34e80 20 7b 48 31 36 34 31 32 7d 20 54 68 65 20 5b 73   {H16412} The [s
34e90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34ea0 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65  ror(C,V,N)] inte
34eb0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
34ec0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
34ed0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75       value of fu
34ee0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
34ef0 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
34f00 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
34f10 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
34f20 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46  ERROR] and a UTF
34f30 2d 38 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  -8 error message
34f40 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75   copied from V u
34f50 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  p to the.**     
34f60 20 20 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20       first zero 
34f70 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20  byte or until N 
34f80 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20 69  bytes are read i
34f90 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e  f N is positive.
34fa0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20  .**.** {H16415} 
34fb0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
34fc0 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c  ult_error16(C,V,
34fd0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  N)] interface ch
34fe0 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
34ff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
35000 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
35010 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
35020 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
35030 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
35040 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61  [SQLITE_ERROR] a
35050 6e 64 20 61 20 55 54 46 2d 31 36 20 6e 61 74 69  nd a UTF-16 nati
35060 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 65 72  ve byte order er
35070 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
35080 20 20 20 20 20 20 20 20 63 6f 70 69 65 64 20 66          copied f
35090 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20  rom V up to the 
350a0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
350b0 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e  nator or until N
350c0 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20   bytes.**       
350d0 20 20 20 61 72 65 20 72 65 61 64 20 69 66 20 4e     are read if N
350e0 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a   is positive..**
350f0 0a 2a 2a 20 7b 48 31 36 34 31 38 7d 20 54 68 65  .** {H16418} The
35100 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35110 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29  _error_toobig(C)
35120 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
35130 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
35140 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
35150 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
35160 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
35170 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
35180 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
35190 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47    [SQLITE_TOOBIG
351a0 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72  ] and an appropr
351b0 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
351c0 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32  ge..**.** {H1642
351d0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
351e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
351f0 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  em(C)] interface
35200 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
35210 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
35220 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
35230 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
35240 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
35250 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
35260 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e         [SQLITE_N
35270 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70  OMEM] and an app
35280 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
35290 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  essage..**.** {H
352a0 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  16424} The [sqli
352b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
352c0 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65  _code(C,E)] inte
352d0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
352e0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
352f0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
35300 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
35310 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
35320 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20  with error code 
35330 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54  E..**          T
35340 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
35350 20 74 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67   text is unchang
35360 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32  ed..**.** {H1642
35370 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
35380 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d  result_int(C,V)]
35390 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
353a0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
353b0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
353c0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
353d0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 69   be the 32-bit i
353e0 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
353f0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54  **.** {H16430} T
35400 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
35410 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69  lt_int64(C,V)] i
35420 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
35430 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
35440 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
35450 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
35460 65 20 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74  e the 64-bit int
35470 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a  eger value V..**
35480 0a 2a 2a 20 7b 48 31 36 34 33 33 7d 20 54 68 65  .** {H16433} The
35490 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
354a0 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66  _null(C)] interf
354b0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
354c0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
354d0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
354e0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c  tion C to be NUL
354f0 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36  L..**.** {H16436
35500 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
35510 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
35520 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
35530 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
35540 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
35550 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
35560 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
35570 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  8 string.**     
35580 20 20 20 20 20 56 20 75 70 20 74 6f 20 74 68 65       V up to the
35590 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
355a0 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
355b0 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
355c0 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
355d0 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
355e0 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
355f0 48 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c  H16439} The [sql
35600 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35610 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74  16(C,V,N,D)] int
35620 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
35630 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
35640 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
35650 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
35660 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
35670 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
35680 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
35690 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
356a0 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e  t zero if N is n
356b0 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
356c0 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74      or the first
356d0 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
356e0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
356f0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34  ve..**.** {H1644
35700 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
35710 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
35720 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
35730 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
35740 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
35750 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
35760 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
35770 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69   UTF-16 big-endi
35780 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
35790 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68  tring V up to th
357a0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
357b0 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
357c0 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
357d0 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
357e0 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  r V if N is non-
357f0 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
35800 7b 48 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71  {H16445} The [sq
35810 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35820 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
35830 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
35840 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
35850 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
35860 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
35870 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 6c 69  be the UTF-16 li
35880 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20  ttle-endian.**  
35890 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56          string V
358a0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
358b0 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65   zero if N is ne
358c0 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
358d0 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20     or the first 
358e0 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20  N bytes of V if 
358f0 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
35900 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38  e..**.** {H16448
35910 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
35920 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29  esult_value(C,V)
35930 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
35940 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
35950 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
35960 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
35970 6f 20 62 65 20 74 68 65 20 5b 75 6e 70 72 6f 74  o be the [unprot
35980 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
35990 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  lue].**         
359a0 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a   object V..**.**
359b0 20 7b 48 31 36 34 35 31 7d 20 54 68 65 20 5b 73   {H16451} The [s
359c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
359d0 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74  roblob(C,N)] int
359e0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
359f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
35a00 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
35a10 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
35a20 61 6e 20 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f  an N-byte BLOB o
35a30 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a  f all zeros..**.
35a40 2a 2a 20 7b 48 31 36 34 35 34 7d 20 54 68 65 20  ** {H16454} The 
35a50 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35a60 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71  error()] and [sq
35a70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35a80 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  or16()].**      
35a90 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d      interfaces m
35aa0 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
35ab0 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67  eir error messag
35ac0 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65  e strings before
35ad0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
35ae0 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  urning..**.** {H
35af0 31 36 34 35 37 7d 20 49 66 20 74 68 65 20 44 20  16457} If the D 
35b00 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d  destructor param
35b10 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
35b20 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
35b30 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
35b40 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
35b50 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
35b60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  )], [sqlite3_res
35b70 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e  ult_text16(C,V,N
35b80 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
35b90 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
35ba0 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
35bb0 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
35bc0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
35bd0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
35be0 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63  V,N,D)] is the c
35bf0 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
35c00 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20  STATIC].**      
35c10 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74      then no dest
35c20 72 75 63 74 6f 72 20 69 73 20 65 76 65 72 20 63  ructor is ever c
35c30 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69  alled on the poi
35c40 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74  nter V and SQLit
35c50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  e.**          as
35c60 73 75 6d 65 73 20 74 68 61 74 20 56 20 69 73 20  sumes that V is 
35c70 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  immutable..**.**
35c80 20 7b 48 31 36 34 36 30 7d 20 49 66 20 74 68 65   {H16460} If the
35c90 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61   D destructor pa
35ca0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
35cb0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
35cc0 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
35cd0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
35ce0 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c  result_text(C,V,
35cf0 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  N,D)], [sqlite3_
35d00 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
35d10 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
35d20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
35d30 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
35d40 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,N,D)], or.**  
35d50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
35d60 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
35d70 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68  (C,V,N,D)] is th
35d80 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20  e constant.**   
35d90 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
35da0 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74  RANSIENT] then t
35db0 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  he interfaces ma
35dc0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
35dd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
35de0 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72  ntent of V and r
35df0 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e  etains the copy.
35e00 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20  .**.** {H16463} 
35e10 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63  If the D destruc
35e20 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tor parameter to
35e30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35e40 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _blob(C,V,N,D)],
35e50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
35e60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35e70 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71  t(C,V,N,D)], [sq
35e80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35e90 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  t16(C,V,N,D)],.*
35ea0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
35eb0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
35ec0 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f  6be(C,V,N,D)], o
35ed0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
35ee0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35ef0 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
35f00 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f   is some value o
35f10 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
35f20 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61        the consta
35f30 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  nts [SQLITE_STAT
35f40 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  IC] and [SQLITE_
35f50 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a  TRANSIENT] then.
35f60 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69  **          SQLi
35f70 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
35f80 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
35f90 77 69 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e  with V as its on
35fa0 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20  ly argument.**  
35fb0 20 20 20 20 20 20 20 20 77 68 65 6e 20 69 74 20          when it 
35fc0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
35fd0 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a  h the V value..*
35fe0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
35ff0 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
36000 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
36010 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
36020 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
36030 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36040 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
36050 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
36060 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
36070 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
36080 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36090 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
360a0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
360b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
360c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
360d0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
360e0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
360f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
36100 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
36110 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
36120 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36130 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
36140 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
36150 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36160 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
36170 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
36180 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
36190 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
361a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
361b0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
361c0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
361d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
361e0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
361f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36200 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
36210 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
36220 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36230 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
36240 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
36250 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
36260 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
36270 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36280 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
36290 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
362a0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
362b0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
362c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
362d0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
362e0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
362f0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
36300 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
36310 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
36320 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
36330 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
36340 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
36350 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
36360 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36370 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
36380 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
36390 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
363a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
363b0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
363c0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
363d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
363e0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
363f0 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20  ating Sequences 
36400 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30  {H16600} <S20300
36410 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  >.**.** These fu
36420 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64  nctions are used
36430 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c   to add new coll
36440 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
36450 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  to the.** [datab
36460 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36470 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
36480 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
36490 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
364a0 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61  of the new colla
364b0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
364c0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20   specified as a 
364d0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
364e0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
364f0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
36500 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
36510 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
36520 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
36530 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69   string for sqli
36540 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36550 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c  tion16(). In all
36560 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61   cases.** the na
36570 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20  me is passed as 
36580 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
36590 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
365a0 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
365b0 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e  gument may be on
365c0 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
365d0 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ts [SQLITE_UTF8]
365e0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
365f0 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  16LE] or [SQLITE
36600 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63  _UTF16BE], indic
36610 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75  ating that the u
36620 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ser-supplied.** 
36630 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
36640 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69  to be passed poi
36650 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
36660 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
36670 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  TF-8,.** UTF-16 
36680 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f  little-endian, o
36690 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64  r UTF-16 big-end
366a0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
366b0 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  y. The.** third 
366c0 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61  argument might a
366d0 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55  lso be [SQLITE_U
366e0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f  TF16_ALIGNED] to
366f0 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a   indicate that.*
36700 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
36710 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
36720 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
36730 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
36740 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68   of UTF-16 in th
36750 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
36760 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
36770 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  computer..**.** 
36780 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
36790 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72   user supplied r
367a0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70  outine must be p
367b0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66  assed as the fif
367c0 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  th.** argument. 
367d0 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
367e0 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  this is the same
367f0 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65   as deleting the
36800 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
36810 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20  quence (so that 
36820 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61  SQLite cannot ca
36830 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a  ll it anymore)..
36840 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65  ** Each time the
36850 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70   application sup
36860 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  plied function i
36870 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73  s invoked, it is
36880 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74   passed.** as it
36890 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
368a0 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  r a copy of the 
368b0 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20  void* passed as 
368c0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
368d0 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
368e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
368f0 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
36900 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36910 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
36920 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65  remaining argume
36930 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69  nts to the appli
36940 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20  cation-supplied 
36950 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20  routine are two 
36960 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68  strings,.** each
36970 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
36980 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29  a (length, data)
36990 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65   pair and encode
369a0 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  d in the encodin
369b0 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61  g.** that was pa
369c0 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
369d0 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20  d argument when 
369e0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  the collation se
369f0 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65  quence was.** re
36a00 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20  gistered. {END} 
36a10 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
36a20 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69   defined collati
36a30 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  on routine shoul
36a40 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61  d.** return nega
36a50 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
36a60 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69  sitive if the fi
36a70 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
36a80 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61  ss than,.** equa
36a90 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
36aa0 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
36ab0 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53   string. i.e. (S
36ac0 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32  TRING1 - STRING2
36ad0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
36ae0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36af0 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
36b00 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
36b10 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
36b20 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
36b30 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72  it takes an extr
36b40 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  a argument which
36b50 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
36b60 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c   for.** the coll
36b70 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74  ation.  The dest
36b80 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
36b90 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
36ba0 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f  ion is.** destro
36bb0 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65  yed and is passe
36bc0 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
36bd0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
36be0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a   void* pointer.*
36bf0 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
36c00 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36c10 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61  n_v2()..** Colla
36c20 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f  tions are destro
36c30 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  yed when they ar
36c40 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
36c50 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74  later calls to t
36c60 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20  he.** collation 
36c70 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
36c80 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b  ns or when the [
36c90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36ca0 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a  ion] is closed.*
36cb0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
36cc0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
36cd0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
36ce0 2a 2a 20 7b 48 31 36 36 30 33 7d 20 41 20 73 75  ** {H16603} A su
36cf0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
36d00 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
36d10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36d20 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
36d30 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65  X,E,P,F,D)] inte
36d40 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  rface.**        
36d50 20 20 72 65 67 69 73 74 65 72 73 20 66 75 6e 63    registers func
36d60 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f  tion F as the co
36d70 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
36d80 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  n used to.**    
36d90 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20        implement 
36da0 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74  collation X on t
36db0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36dc0 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a  nection] B for.*
36dd0 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
36de0 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f  ases having enco
36df0 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ding E..**.** {H
36e00 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e  16604} SQLite un
36e10 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 58 20  derstands the X 
36e20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
36e30 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
36e40 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36e50 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
36e60 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65  D)] as a zero-te
36e70 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
36e80 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
36e90 67 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  g in which case 
36ea0 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41  is ignored for A
36eb0 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 20  SCII characters 
36ec0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
36ed0 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66  is significant f
36ee0 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61  or non-ASCII cha
36ef0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b  racters..**.** {
36f00 48 31 36 36 30 36 7d 20 53 75 63 63 65 73 73 69  H16606} Successi
36f10 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ve calls to [sql
36f20 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36f30 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
36f40 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
36f50 20 20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65     with the same
36f60 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58   values for B, X
36f70 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64  , and E, overrid
36f80 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a  e prior values.*
36f90 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c  *          of P,
36fa0 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a   F, and D..**.**
36fb0 20 7b 48 31 36 36 30 39 7d 20 49 66 20 74 68 65   {H16609} If the
36fc0 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e   destructor D in
36fd0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36fe0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
36ff0 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
37000 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e          is not N
37010 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63  ULL then it is c
37020 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d  alled with argum
37030 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a  ent P when the.*
37040 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
37050 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
37060 20 64 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69   dropped by SQLi
37070 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31  te..**.** {H1661
37080 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  2} A collating f
37090 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70  unction is dropp
370a0 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76  ed when it is ov
370b0 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  erloaded..**.** 
370c0 7b 48 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61  {H16615} A colla
370d0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
370e0 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68   dropped when th
370f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
37100 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
37110 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e    is closed usin
37120 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
37130 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  ()]..**.** {H166
37140 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20  18} The pointer 
37150 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72  P in [sqlite3_cr
37160 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
37170 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a  2(B,X,E,P,F,D)].
37180 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70  **          is p
37190 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
371a0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
371b0 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70  eter to the comp
371c0 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
371d0 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f     function F fo
371e0 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  r all subsequent
371f0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
37200 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31  F..**.** {H16621
37210 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  } A call to [sql
37220 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37230 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29  ation(B,X,E,P,F)
37240 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20  ] is exactly.** 
37250 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
37260 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b  e as a call to [
37270 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37280 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77  ollation_v2()] w
37290 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
372a0 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74  the same paramet
372b0 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64  ers and a NULL d
372c0 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a  estructor..**.**
372d0 20 7b 48 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77   {H16624} Follow
372e0 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63  ing a [sqlite3_c
372f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
37300 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
37310 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  ,.**          SQ
37320 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 63 6f  Lite uses the co
37330 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
37340 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74  n F for all text
37350 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20   comparison.**  
37360 20 20 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f          operatio
37370 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ns on the [datab
37380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37390 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73  B on text values
373a0 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
373b0 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74    use the collat
373c0 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d  ing sequence nam
373d0 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ed X..**.** {H16
373e0 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  627} The [sqlite
373f0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37400 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d  on16(B,X,E,P,F)]
37410 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a   works the same.
37420 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 5b  **          as [
37430 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37440 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50  ollation(B,X,E,P
37450 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  ,F)] except that
37460 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
37470 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20   collation name 
37480 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20  X is understood 
37490 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
374a0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
374b0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 74 65  *          inste
374c0 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a  ad of UTF-8..**.
374d0 2a 2a 20 7b 48 31 36 36 33 30 7d 20 57 68 65 6e  ** {H16630} When
374e0 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72   multiple compar
374f0 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61  ison functions a
37500 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72  re available for
37510 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
37520 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
37530 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65  sequence, SQLite
37540 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65   chooses the one
37550 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f   whose text enco
37560 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
37570 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
37580 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  ast amount of co
37590 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68  nversion from th
375a0 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20  e default.**    
375b0 20 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64        text encod
375c0 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
375d0 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ase..*/.int sqli
375e0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
375f0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
37600 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
37610 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
37620 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
37630 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
37640 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
37650 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
37660 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
37670 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
37680 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
37690 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
376a0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
376b0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
376c0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
376d0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
376e0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
376f0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
37700 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
37710 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
37720 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
37730 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
37740 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
37750 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
37760 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
37770 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
37780 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
37790 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
377a0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
377b0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
377c0 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
377d0 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
377e0 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32  cks {H16700} <S2
377f0 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  0300>.**.** To a
37800 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
37810 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
37820 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
37830 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
37840 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
37850 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
37860 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
37870 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
37880 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
37890 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
378a0 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68   to be called wh
378b0 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
378c0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
378d0 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
378e0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  uired..**.** If 
378f0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
37900 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
37910 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
37920 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
37930 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
37940 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
37950 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
37960 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
37970 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
37980 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
37990 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66  F-8. {H16703} If
379a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
379b0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
379c0 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
379d0 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
379e0 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
379f0 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
37a00 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c  order..** A call
37a10 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
37a20 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79  ion replaces any
37a30 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61   existing callba
37a40 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ck..**.** When t
37a50 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
37a60 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
37a70 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
37a80 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
37a90 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
37aa0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
37ab0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
37ac0 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
37ad0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37ae0 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
37af0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
37b00 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
37b10 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
37b20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
37b30 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
37b40 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
37b50 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
37b60 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
37b70 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
37b80 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
37b90 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
37ba0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
37bb0 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
37bc0 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
37bd0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
37be0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
37bf0 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
37c00 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a  tion sequence..*
37c10 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
37c20 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
37c30 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
37c40 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
37c50 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
37c60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37c70 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
37c80 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37c90 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
37ca0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37cb0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
37cc0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
37cd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20  .**.** {H16702} 
37ce0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
37cf0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
37d00 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44  llation_needed(D
37d10 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,P,F)].**       
37d20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
37d30 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
37d40 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73  6(D,P,F)] causes
37d50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
37d60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37d70 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f  ction] D to invo
37d80 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69  ke callback F wi
37d90 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  th first.**     
37da0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 50       parameter P
37db0 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65   whenever it nee
37dc0 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20  ds a comparison 
37dd0 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a  function for a.*
37de0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
37df0 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68  ting sequence th
37e00 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b  at it does not k
37e10 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a  now about..**.**
37e20 20 7b 48 31 36 37 30 34 7d 20 45 61 63 68 20 73   {H16704} Each s
37e30 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
37e40 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  o [sqlite3_colla
37e50 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f  tion_needed()] o
37e60 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
37e70 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37e80 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65  _needed16()] ove
37e90 72 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62  rrides the callb
37ea0 61 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a  ack registered.*
37eb0 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68  *          on th
37ec0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
37ed0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20   connection] by 
37ee0 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65  prior calls to e
37ef0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
37f00 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a    interface..**.
37f10 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54 68 65 20  ** {H16706} The 
37f20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75  name of the requ
37f30 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20  ested collating 
37f40 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20  function passed 
37f50 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
37f60 20 20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72     4th parameter
37f70 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
37f80 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20   is in UTF-8 if 
37f90 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
37fa0 20 20 20 20 20 20 20 20 20 77 61 73 20 72 65 67           was reg
37fb0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73  istered using [s
37fc0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37fd0 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a  _needed()] and.*
37fe0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
37ff0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
38000 79 74 65 20 6f 72 64 65 72 20 69 66 20 74 68 65  yte order if the
38010 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a   callback was.**
38020 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
38030 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ered using [sqli
38040 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
38050 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  eded16()]..*/.in
38060 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
38070 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
38080 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
38090 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
380a0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
380b0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
380c0 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
380d0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
380e0 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
380f0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
38100 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
38110 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
38120 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
38130 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  ).);../*.** Spec
38140 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
38150 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
38160 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
38170 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
38180 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
38190 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
381a0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
381b0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
381c0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
381d0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
381e0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
381f0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
38200 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
38210 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
38220 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
38230 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
38240 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
38250 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
38260 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
38270 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
38280 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
38290 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
382a0 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
382b0 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
382c0 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
382d0 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
382e0 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
382f0 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
38300 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
38310 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
38320 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
38330 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
38340 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
38350 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
38360 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
38370 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
38380 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
38390 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
383a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
383b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
383c0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
383d0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
383e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
383f0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
38400 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
38410 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
38420 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65  REF: Suspend Exe
38430 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
38440 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d  rt Time {H10530}
38450 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S40410>.**.** 
38460 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
38470 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
38480 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
38490 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
384a0 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
384b0 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
384c0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
384d0 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
384e0 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
384f0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
38500 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
38510 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
38520 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
38530 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
38540 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
38550 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
38560 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
38570 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
38580 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
38590 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
385a0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
385b0 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
385c0 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
385d0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
385e0 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
385f0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
38600 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
38610 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
38620 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
38630 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
38640 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
38650 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
38660 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
38670 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54  **.** {H10533} T
38680 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
38690 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
386a0 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65  invokes the xSle
386b0 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ep.**          m
386c0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
386d0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
386e0 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20  s|VFS] in order 
386f0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  to.**          s
38700 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
38710 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
38720 74 68 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65  thread for at le
38730 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ast.**          
38740 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a  M milliseconds..
38750 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54  **.** {H10536} T
38760 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
38770 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
38780 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
38790 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
387a0 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f    milliseconds o
387b0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
387c0 20 72 65 71 75 65 73 74 65 64 20 6f 66 20 74 68   requested of th
387d0 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20  e operating.**  
387e0 20 20 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20          system, 
387f0 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c  which might be l
38800 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 70  arger than the p
38810 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69  arameter M..*/.i
38820 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
38830 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
38840 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
38850 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
38860 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
38870 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30  es {H10310} <S20
38880 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  000>.**.** If th
38890 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
388a0 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
388b0 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
388c0 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
388d0 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
388e0 20