/ Hex Artifact Content
Login

Artifact 4d05b9195e9489dc62857d9dd3334b0139715101:


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 34 20 32 30 30 38 2f 31  n,v 1.414 2008/1
05f0: 31 2f 31 38 20 31 39 3a 31 38 3a 30 39 20 64 72  1/18 19:18:09 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20  .** These no-op 
0750: 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20  macros are used 
0760: 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65  in front of inte
0770: 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74  rfaces to mark t
0780: 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hose.** interfac
0790: 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70  es as either dep
07a0: 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72  recated or exper
07b0: 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70  imental.  New ap
07c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
07d0: 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70  ould not use dep
07e0: 72 65 63 61 74 65 64 20 69 6e 74 72 66 61 63 65  recated intrface
07f0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
0800: 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77 61 72  port for backwar
0810: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
0820: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
0830: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
0840: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
0850: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
0860: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
0870: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0880: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0890: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
08a0: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
08b0: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
08c0: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
08d0: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
08e0: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
08f0: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0900: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0910: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
0920: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
0930: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
0940: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
0950: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
0960: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
0970: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0980: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0990: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
09a0: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
09b0: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
09c0: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
09d0: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
09e0: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
09f0: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a00: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a10: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0a20: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0a30: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0a40: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0a50: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0a60: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0a70: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0a80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0a90: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0aa0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0ab0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0ac0: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0ad0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0ae0: 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31  n Numbers {H1001
0af0: 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S60100>.**.*
0b00: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0b10: 53 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f  SION and SQLITE_
0b20: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23  VERSION_NUMBER #
0b30: 64 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68  defines in.** th
0b40: 65 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65  e sqlite3.h file
0b50: 20 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72   specify the ver
0b60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77  sion of SQLite w
0b70: 69 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61  ith which.** tha
0b80: 74 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73  t header file is
0b90: 20 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a   associated..**.
0ba0: 2a 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22  ** The "version"
0bb0: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20   of SQLite is a 
0bc0: 73 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f  string of the fo
0bd0: 72 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54  rm "X.Y.Z"..** T
0be0: 68 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61  he phrase "alpha
0bf0: 22 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68  " or "beta" migh
0c00: 74 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66  t be appended af
0c10: 74 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68  ter the Z..** Th
0c20: 65 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a  e X value is maj
0c30: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0c40: 72 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51  r always 3 in SQ
0c50: 4c 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20  Lite3..** The X 
0c60: 76 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67  value only chang
0c70: 65 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64  es when backward
0c80: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
0c90: 69 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64  is.** broken and
0ca0: 20 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65   we intend to ne
0cb0: 76 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61  ver break backwa
0cc0: 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
0cd0: 79 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75  y..** The Y valu
0ce0: 65 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  e is the minor v
0cf0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
0d00: 64 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77  d only changes w
0d10: 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65  hen.** there are
0d20: 20 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65   major feature e
0d30: 6e 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74  nhancements that
0d40: 20 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f   are forwards co
0d50: 6d 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20  mpatible.** but 
0d60: 6e 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f  not backwards co
0d70: 6d 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65  mpatible..** The
0d80: 20 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20   Z value is the 
0d90: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61  release number a
0da0: 6e 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65  nd is incremente
0db0: 64 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72  d with.** each r
0dc0: 65 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74  elease but reset
0dd0: 73 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e  s back to 0 when
0de0: 65 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d  ever Y is increm
0df0: 65 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ented..**.** See
0e00: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
0e10: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  libversion()] an
0e20: 64 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  d [sqlite3_libve
0e30: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e  rsion_number()].
0e40: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
0e50: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31  S:.**.** {H10011
0e60: 7d 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  } The SQLITE_VER
0e70: 53 49 4f 4e 20 23 64 65 66 69 6e 65 20 69 6e 20  SION #define in 
0e80: 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65  the sqlite3.h he
0e90: 61 64 65 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a  ader file shall.
0ea0: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 76 61 6c  **          eval
0eb0: 75 61 74 65 20 74 6f 20 61 20 73 74 72 69 6e 67  uate to a string
0ec0: 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73   literal that is
0ed0: 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73   the SQLite vers
0ee0: 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
0ef0: 77 69 74 68 20 77 68 69 63 68 20 74 68 65 20 68  with which the h
0f00: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73  eader file is as
0f10: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  sociated..**.** 
0f20: 7b 48 31 30 30 31 34 7d 20 54 68 65 20 53 51 4c  {H10014} The SQL
0f30: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0f40: 45 52 20 23 64 65 66 69 6e 65 20 73 68 61 6c 6c  ER #define shall
0f50: 20 72 65 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69   resolve to an i
0f60: 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
0f70: 20 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75     with the valu
0f80: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0f90: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0fa0: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20   X, Y, and Z.** 
0fb0: 20 20 20 20 20 20 20 20 20 61 72 65 20 74 68 65           are the
0fc0: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20   major version, 
0fd0: 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61  minor version, a
0fe0: 6e 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  nd release numbe
0ff0: 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  r..*/.#define SQ
1000: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1010: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
1020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1030: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d  ERSION_NUMBER  -
1040: 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d  -VERSION-NUMBER-
1050: 2d 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  -../*.** CAPI3RE
1060: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72  F: Run-Time Libr
1070: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62  ary Version Numb
1080: 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c 53 36  ers {H10020} <S6
1090: 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0100>.** KEYWORD
10a0: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
10b0: 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  on.**.** These f
10c0: 65 61 74 75 72 65 73 20 70 72 6f 76 69 64 65 20  eatures provide 
10d0: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
10e0: 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c  tion as the [SQL
10f0: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20  ITE_VERSION].** 
1100: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  and [SQLITE_VERS
1110: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66  ION_NUMBER] #def
1120: 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61 64  ines in the head
1130: 65 72 2c 20 62 75 74 20 61 72 65 20 61 73 73 6f  er, but are asso
1140: 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
1150: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1160: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
1170: 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75 73   file.  Cautious
1180: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
1190: 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20  ht.** include a 
11a0: 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72 20 61  check in their a
11b0: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 76 65  pplication to ve
11c0: 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c  rify that.** sql
11d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
11e0: 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 73 20  number() always 
11f0: 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
1200: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  e.** [SQLITE_VER
1210: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a  SION_NUMBER]..**
1220: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1230: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1240: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1250: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1260: 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74  on as is.** in t
1270: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
1280: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1290: 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e 63 74  tant.  The funct
12a0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 0a  ion is provided.
12b0: 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c  ** for use in DL
12c0: 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65  Ls since DLL use
12d0: 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f  rs usually do no
12e0: 74 20 68 61 76 65 20 64 69 72 65 63 74 20 61 63  t have direct ac
12f0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a  cess to string.*
1300: 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68  * constants with
1310: 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a  in the DLL..**.*
1320: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1330: 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54 68 65  .** {H10021} The
1340: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
1350: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69  sion_number()] i
1360: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72  nterface shall r
1370: 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
1380: 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75    an integer equ
1390: 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45  al to [SQLITE_VE
13a0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a  RSION_NUMBER]..*
13b0: 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20 54 68  *.** {H10022} Th
13c0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69  e [sqlite3_versi
13d0: 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  on] string const
13e0: 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69  ant shall contai
13f0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
1400: 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 5b 53  e text of the [S
1410: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73  QLITE_VERSION] s
1420: 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
1430: 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  0023} The [sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d  e3_libversion()]
1450: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
1460: 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
1470: 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20     a pointer to 
1480: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72  the [sqlite3_ver
1490: 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e  sion] string con
14a0: 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  stant..*/.SQLITE
14b0: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
14c0: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
14d0: 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72  on[];.const char
14e0: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
14f0: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20  sion(void);.int 
1500: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1510: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
1520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1530: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1540: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1550: 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 30 31  Threadsafe {H101
1560: 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a  00} <S60100>.**.
1570: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1580: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1590: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
15a0: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
15b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
15c0: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
15d0: 6f 72 20 6d 61 63 72 6f 20 31 20 6f 72 20 32 2c  or macro 1 or 2,
15e0: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
15f0: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1600: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1610: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1620: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1630: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1640: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1650: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1660: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1670: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1680: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1690: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
16a0: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
16b0: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
16c0: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
16d0: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
16e0: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
16f0: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1700: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1710: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1720: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1730: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1740: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1750: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1760: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1770: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1780: 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62  ** The default b
1790: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
17a0: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
17b0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
17c0: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
17d0: 65 20 75 73 65 64 20 62 79 20 61 20 70 72 6f 67  e used by a prog
17e0: 72 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ram to make sure
17f0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72   that the.** ver
1800: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74  sion of SQLite t
1810: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e  hat it is linkin
1820: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f  g against was co
1830: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
1840: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69  he desired setti
1850: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ng of the [SQLIT
1860: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1870: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cro..**.** This 
1880: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
1890: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f  eports on the co
18a0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78  mpile-time mutex
18b0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74   setting.** of t
18c0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
18d0: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66  DSAFE] flag.  If
18e0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
18f0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49  led with.** SQLI
1900: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20  TE_THREADSAFE=1 
1910: 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65  then mutexes are
1920: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
1930: 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62  ult but.** can b
1940: 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69  e fully or parti
1950: 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73  ally disabled us
1960: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73  ing a call to [s
1970: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
1980: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72  .** with the ver
1990: 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  bs [SQLITE_CONFI
19a0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c  G_SINGLETHREAD],
19b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
19c0: 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a  MULTITHREAD],.**
19d0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
19e0: 49 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20  IG_MUTEX].  The 
19f0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
1a00: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
1a10: 6f 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20  ows.** only the 
1a20: 64 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d  default compile-
1a30: 74 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f  time setting, no
1a40: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
1a50: 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61  hanges.** to tha
1a60: 74 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  t setting..**.**
1a70: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
1a80: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
1a90: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
1aa0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1ab0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  on..**.** INVARI
1ac0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ANTS:.**.** {H10
1ad0: 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  101} The [sqlite
1ae0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1af0: 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72  function shall r
1b00: 65 74 75 72 6e 20 7a 65 72 6f 20 69 66 0a 2a 2a  eturn zero if.**
1b10: 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 6f 6e            and on
1b20: 6c 79 20 69 66 20 53 51 4c 69 74 65 20 77 61 73  ly if SQLite was
1b30: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1b40: 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69  utexing code omi
1b50: 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  tted..**.** {H10
1b60: 31 30 32 7d 20 54 68 65 20 76 61 6c 75 65 20 72  102} The value r
1b70: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 5b  eturned by the [
1b80: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1b90: 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  fe()] function.*
1ba0: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
1bb0: 20 72 65 6d 61 69 6e 20 74 68 65 20 73 61 6d 65   remain the same
1bc0: 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f   across calls to
1bd0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
1be0: 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1bf0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76  te3_threadsafe(v
1c00: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
1c10: 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
1c20: 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c  Connection Handl
1c30: 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30 32  e {H12000} <S402
1c40: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1c50: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
1c60: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
1c70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
1c80: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
1c90: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
1ca0: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
1cb0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
1cc0: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
1cd0: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
1ce0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
1cf0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
1d00: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
1d10: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
1d20: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
1d30: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
1d40: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1d50: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1d60: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
1d70: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
1d80: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
1d90: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
1da0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
1db0: 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72 75  ** is its destru
1dc0: 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72 65  ctor.  There are
1dd0: 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74 65   many other inte
1de0: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
1df0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1e00: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
1e10: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
1e20: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
1e30: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1e40: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
1e50: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
1e60: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
1e70: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
1e80: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
1e90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
1ea0: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
1eb0: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
1ec0: 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b 48  Integer Types {H
1ed0: 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a  10200} <S10110>.
1ee0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
1ef0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
1f00: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
1f10: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
1f20: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
1f30: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
1f40: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
1f50: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
1f60: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
1f70: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
1f80: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
1f90: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
1fa0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
1fb0: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
1fc0: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
1fd0: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69  ferred type defi
1fe0: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nitions..** The 
1ff0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64  sqlite_int64 and
2000: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
2010: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74  ypes are support
2020: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
2030: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
2040: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e  y only..**.** IN
2050: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2060: 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b 73 71  {H10201} The [sq
2070: 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20  lite_int64] and 
2080: 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20  [sqlite3_int64] 
2090: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
20a0: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
20b0: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
20c0: 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nteger..**.** {H
20d0: 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  10202} The [sqli
20e0: 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b  te_uint64] and [
20f0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d 20  sqlite3_uint64] 
2100: 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63 69  type shall speci
2110: 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  fy.**          a
2120: 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
2130: 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66   integer..*/.#if
2140: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2150: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
2160: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2170: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
2180: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2190: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
21a0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
21b0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
21c0: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
21d0: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
21e0: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
21f0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2200: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2210: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2220: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2230: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2240: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2250: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2260: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
2270: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2280: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
2290: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
22a0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
22b0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
22c0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
22d0: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
22e0: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
22f0: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2300: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2310: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2320: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2330: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2340: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2350: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
2360: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
2370: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
2380: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
2390: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
23a0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
23b0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
23c0: 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c  ction {H12010} <
23d0: 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a  S30100><S40200>.
23e0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
23f0: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2400: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2410: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2420: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
2430: 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65  s should [sqlite
2440: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2450: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2460: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2470: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2480: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2490: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
24a0: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
24b0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
24c0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
24d0: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
24e0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
24f0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20   object..** The 
2500: 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2510: 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  mt()] interface 
2520: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
2530: 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72  ocate all.** [pr
2540: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2550: 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  s] associated wi
2560: 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
2570: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64 65  onnection] if de
2580: 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61  sired..** Typica
2590: 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f  l code might loo
25a0: 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  k like this:.**.
25b0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
25c0: 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  pre>.** sqlite3_
25d0: 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20  stmt *pStmt;.** 
25e0: 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d 20  while( (pStmt = 
25f0: 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2600: 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a  t(db, 0))!=0 ){.
2610: 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c 69  ** &nbsp;   sqli
2620: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74  te3_finalize(pSt
2630: 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70  mt);.** }.** </p
2640: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
2650: 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  .**.** If [sqlit
2660: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69  e3_close()] is i
2670: 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74  nvoked while a t
2680: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
2690: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
26a0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
26b0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
26c0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ack..**.** INVAR
26d0: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
26e0: 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 73 66  2011} A successf
26f0: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2700: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68  te3_close(C)] sh
2710: 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 65 0a  all destroy the.
2720: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
2730: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2740: 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a  ] object C..**.*
2750: 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73 75 63  * {H12012} A suc
2760: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2770: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2780: 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  )] shall return 
2790: 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a  SQLITE_OK..**.**
27a0: 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75 63 63   {H12013} A succ
27b0: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
27c0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
27d0: 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 65 20  ] shall release 
27e0: 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
27f0: 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 74 65  memory and syste
2800: 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 73 6f  m resources asso
2810: 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 61 74  ciated with [dat
2820: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2830: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 2e  ].**          C.
2840: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 7d 20  .**.** {H12014} 
2850: 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
2860: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20  e3_close(C)] on 
2870: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
2880: 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a  ection] C that.*
2890: 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 20 6f  *          has o
28a0: 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20  ne or more open 
28b0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28c0: 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c  ents] shall fail
28d0: 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
28e0: 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53    an [SQLITE_BUS
28f0: 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a  Y] error code..*
2900: 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 41 20  *.** {H12015} A 
2910: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2920: 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72 65  _close(C)] where
2930: 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   C is a NULL poi
2940: 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  nter shall.**   
2950: 20 20 20 20 20 20 20 62 65 20 61 20 68 61 72 6d         be a harm
2960: 6c 65 73 73 20 6e 6f 2d 6f 70 20 72 65 74 75 72  less no-op retur
2970: 6e 69 6e 67 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  ning SQLITE_OK..
2980: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 39 7d 20 57  **.** {H12019} W
2990: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  hen [sqlite3_clo
29a0: 73 65 28 43 29 5d 20 69 73 20 69 6e 76 6f 6b 65  se(C)] is invoke
29b0: 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65  d on a [database
29c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 43 0a 2a   connection] C.*
29d0: 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
29e0: 68 61 73 20 61 20 70 65 6e 64 69 6e 67 20 74 72  has a pending tr
29f0: 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 20 74  ansaction, the t
2a00: 72 61 6e 73 61 63 74 69 6f 6e 20 73 68 61 6c 6c  ransaction shall
2a10: 20 62 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   be.**          
2a20: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
2a30: 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
2a40: 2a 2a 0a 2a 2a 20 7b 41 31 32 30 31 36 7d 20 54  **.** {A12016} T
2a50: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74  he C parameter t
2a60: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
2a70: 28 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74  (C)] must be eit
2a80: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 20 20  her a NULL.**   
2a90: 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 6f         pointer o
2aa0: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2ab0: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2ac0: 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  tained.**       
2ad0: 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33     from [sqlite3
2ae0: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2af0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
2b00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2b10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2b20: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
2b30: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2f 0a  usly closed..*/.
2b40: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2b50: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2b60: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2b70: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2b80: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2b90: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2ba0: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2bb0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2bc0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2bd0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2be0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2bf0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2c00: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2c10: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2c20: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2c30: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2c40: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2c50: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2c60: 65 20 7b 48 31 32 31 30 30 7d 20 3c 53 31 30 30  e {H12100} <S100
2c70: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74  lite3_exec() int
2c90: 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76  erface is a conv
2ca0: 65 6e 69 65 6e 74 20 77 61 79 20 6f 66 20 72 75  enient way of ru
2cb0: 6e 6e 69 6e 67 20 6f 6e 65 20 6f 72 20 6d 6f 72  nning one or mor
2cc0: 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
2cd0: 6e 74 73 20 77 69 74 68 6f 75 74 20 68 61 76 69  nts without havi
2ce0: 6e 67 20 74 6f 20 77 72 69 74 65 20 61 20 6c 6f  ng to write a lo
2cf0: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 20 54 68  t of C code.  Th
2d00: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 0a  e UTF-8 encoded.
2d10: 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
2d20: 73 20 61 72 65 20 70 61 73 73 65 64 20 69 6e 20  s are passed in 
2d30: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
2d40: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2d50: 65 33 5f 65 78 65 63 28 29 2e 0a 2a 2a 20 54 68  e3_exec()..** Th
2d60: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  e statements are
2d70: 20 65 76 61 6c 75 61 74 65 64 20 6f 6e 65 20 62   evaluated one b
2d80: 79 20 6f 6e 65 20 75 6e 74 69 6c 20 65 69 74 68  y one until eith
2d90: 65 72 20 61 6e 20 65 72 72 6f 72 20 6f 72 0a 2a  er an error or.*
2da0: 2a 20 61 6e 20 69 6e 74 65 72 72 75 70 74 20 69  * an interrupt i
2db0: 73 20 65 6e 63 6f 75 6e 74 65 72 65 64 2c 20 6f  s encountered, o
2dc0: 72 20 75 6e 74 69 6c 20 74 68 65 79 20 61 72 65  r until they are
2dd0: 20 61 6c 6c 20 64 6f 6e 65 2e 20 20 54 68 65 20   all done.  The 
2de0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  3rd parameter.**
2df0: 20 69 73 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20   is an optional 
2e00: 63 61 6c 6c 62 61 63 6b 20 74 68 61 74 20 69 73  callback that is
2e10: 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
2e20: 72 20 65 61 63 68 20 72 6f 77 20 6f 66 20 61 6e  r each row of an
2e30: 79 20 71 75 65 72 79 0a 2a 2a 20 72 65 73 75 6c  y query.** resul
2e40: 74 73 20 70 72 6f 64 75 63 65 64 20 62 79 20 74  ts produced by t
2e50: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2e60: 73 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61  s.  The 5th para
2e70: 6d 65 74 65 72 20 74 65 6c 6c 73 20 77 68 65 72  meter tells wher
2e80: 65 0a 2a 2a 20 74 6f 20 77 72 69 74 65 20 61 6e  e.** to write an
2e90: 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 73  y error messages
2ea0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65 72 72 6f  ..**.** The erro
2eb0: 72 20 6d 65 73 73 61 67 65 20 70 61 73 73 65 64  r message passed
2ec0: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
2ed0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
2ee0: 69 73 20 68 65 6c 64 0a 2a 2a 20 69 6e 20 6d 65  is held.** in me
2ef0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2f00: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2f10: 6f 63 28 29 5d 2e 20 20 54 6f 20 61 76 6f 69 64  oc()].  To avoid
2f20: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2c 0a   a memory leak,.
2f30: 2a 2a 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 61  ** the calling a
2f40: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
2f50: 64 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  d call [sqlite3_
2f60: 66 72 65 65 28 29 5d 20 6f 6e 20 61 6e 79 20 65  free()] on any e
2f70: 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
2f80: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68  returned through
2f90: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
2fa0: 65 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  er when it has f
2fb0: 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a  inished using.**
2fc0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
2fd0: 67 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ge..**.** If the
2fe0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
2ff0: 6e 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  n the 2nd parame
3000: 74 65 72 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  ter is NULL or a
3010: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 0a 2a  n empty string.*
3020: 2a 20 6f 72 20 61 20 73 74 72 69 6e 67 20 63 6f  * or a string co
3030: 6e 74 61 69 6e 69 6e 67 20 6f 6e 6c 79 20 77 68  ntaining only wh
3040: 69 74 65 73 70 61 63 65 20 61 6e 64 20 63 6f 6d  itespace and com
3050: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53  ments, then no S
3060: 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  QL.** statements
3070: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
3080: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  nd the database 
3090: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a  is not changed..
30a0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
30b0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
30c0: 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
30d0: 64 20 69 6e 20 74 65 72 6d 73 20 6f 66 0a 2a 2a  d in terms of.**
30e0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30f0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3100: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
3110: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3120: 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ()]..** The sqli
3130: 74 65 33 5f 65 78 65 63 28 29 20 72 6f 75 74 69  te3_exec() routi
3140: 6e 65 20 64 6f 65 73 20 6e 6f 74 68 69 6e 67 20  ne does nothing 
3150: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
3160: 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 64  that cannot be d
3170: 6f 6e 65 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  one.** by [sqlit
3180: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
3190: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
31a0: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
31b0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
31c0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
31d0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 31 7d 20 41  **.** {H12101} A
31e0: 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
31f0: 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
3200: 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c  e3_exec(D,S,C,A,
3210: 45 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  E)].**          
3220: 73 68 61 6c 6c 20 73 65 71 75 65 6e 74 69 61 6c  shall sequential
3230: 6c 79 20 65 76 61 6c 75 61 74 65 20 61 6c 6c 20  ly evaluate all 
3240: 6f 66 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  of the UTF-8 enc
3250: 6f 64 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  oded,.**        
3260: 20 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61    semicolon-sepa
3270: 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
3280: 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
3290: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
32a0: 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 53          string S
32b0: 20 77 69 74 68 69 6e 20 74 68 65 20 63 6f 6e 74   within the cont
32c0: 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ext of the [data
32d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32e0: 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30   D..**.** {H1210
32f0: 32 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  2} If the S para
3300: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3310: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3320: 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 0a  )] is NULL then.
3330: 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
3340: 61 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 69  actions of the i
3350: 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 62  nterface shall b
3360: 65 20 74 68 65 20 73 61 6d 65 20 61 73 20 69 66  e the same as if
3370: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
3380: 20 53 20 70 61 72 61 6d 65 74 65 72 20 77 65 72   S parameter wer
3390: 65 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  e an empty strin
33a0: 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 34  g..**.** {H12104
33b0: 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
33c0: 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  ue of [sqlite3_e
33d0: 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20  xec()] shall be 
33e0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 61  [SQLITE_OK] if a
33f0: 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ll.**          S
3400: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 72 75  QL statements ru
3410: 6e 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61  n successfully a
3420: 6e 64 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  nd to completion
3430: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 35 7d  ..**.** {H12105}
3440: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
3450: 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78  e of [sqlite3_ex
3460: 65 63 28 29 5d 20 73 68 61 6c 6c 20 62 65 20 61  ec()] shall be a
3470: 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
3480: 20 20 20 20 20 20 20 20 20 20 6e 6f 6e 2d 7a 65            non-ze
3490: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
34a0: 69 66 20 61 6e 79 20 53 51 4c 20 73 74 61 74 65  if any SQL state
34b0: 6d 65 6e 74 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  ment fails..**.*
34c0: 2a 20 7b 48 31 32 31 30 37 7d 20 49 66 20 6f 6e  * {H12107} If on
34d0: 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
34e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
34f0: 68 61 6e 64 65 64 20 74 6f 20 5b 73 71 6c 69 74  handed to [sqlit
3500: 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20 20  e3_exec()].**   
3510: 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 72 65         return re
3520: 73 75 6c 74 73 20 61 6e 64 20 74 68 65 20 33 72  sults and the 3r
3530: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
3540: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 0a 2a 2a  ot NULL, then.**
3550: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61            the ca
3560: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3570: 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
3580: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 73   3rd parameter s
3590: 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20  hall be.**      
35a0: 20 20 20 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65      invoked once
35b0: 20 66 6f 72 20 65 61 63 68 20 72 6f 77 20 6f 66   for each row of
35c0: 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b   result..**.** {
35d0: 48 31 32 31 31 30 7d 20 49 66 20 74 68 65 20 63  H12110} If the c
35e0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
35f0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65  a non-zero value
3600: 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 65   then [sqlite3_e
3610: 78 65 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  xec()].**       
3620: 20 20 20 73 68 61 6c 6c 20 61 62 6f 72 74 20 74     shall abort t
3630: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3640: 20 69 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79   it is currently
3650: 20 65 76 61 6c 75 61 74 69 6e 67 2c 0a 2a 2a 20   evaluating,.** 
3660: 20 20 20 20 20 20 20 20 20 73 6b 69 70 20 61 6c           skip al
3670: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c  l subsequent SQL
3680: 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64   statements, and
3690: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
36a0: 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ABORT]..**.** {H
36b0: 31 32 31 31 33 7d 20 54 68 65 20 5b 73 71 6c 69  12113} The [sqli
36c0: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74  te3_exec()] rout
36d0: 69 6e 65 20 73 68 61 6c 6c 20 70 61 73 73 20 69  ine shall pass i
36e0: 74 73 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  ts 4th parameter
36f0: 20 74 68 72 6f 75 67 68 0a 2a 2a 20 20 20 20 20   through.**     
3700: 20 20 20 20 20 61 73 20 74 68 65 20 31 73 74 20       as the 1st 
3710: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
3720: 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
3730: 20 7b 48 31 32 31 31 36 7d 20 54 68 65 20 5b 73   {H12116} The [s
3740: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
3750: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74  outine shall set
3760: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3770: 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20  er of its.**    
3780: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74        callback t
3790: 6f 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  o be the number 
37a0: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
37b0: 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
37c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
37d0: 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ult..**.** {H121
37e0: 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
37f0: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65  _exec()] routine
3800: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 33   shall set the 3
3810: 72 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  rd parameter of 
3820: 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
3830: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 61  callback to be a
3840: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3850: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 68  ers to strings h
3860: 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  olding the.**   
3870: 20 20 20 20 20 20 20 76 61 6c 75 65 73 20 66 6f         values fo
3880: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 69 6e  r each column in
3890: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 73   the current res
38a0: 75 6c 74 20 73 65 74 20 72 6f 77 20 61 73 0a 2a  ult set row as.*
38b0: 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69  *          obtai
38c0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
38d0: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
38e0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 32 7d  ..**.** {H12122}
38f0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
3900: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  ec()] routine sh
3910: 61 6c 6c 20 73 65 74 20 74 68 65 20 34 74 68 20  all set the 4th 
3920: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73  parameter of its
3930: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c  .**          cal
3940: 6c 62 61 63 6b 20 74 6f 20 62 65 20 61 6e 20 61  lback to be an a
3950: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3960: 20 74 6f 20 73 74 72 69 6e 67 73 20 68 6f 6c 64   to strings hold
3970: 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ing the.**      
3980: 20 20 20 20 6e 61 6d 65 73 20 6f 66 20 72 65 73      names of res
3990: 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 61 73 20 6f  ult columns as o
39a0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
39b0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
39c0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  e()]..**.** {H12
39d0: 31 32 35 7d 20 49 66 20 74 68 65 20 33 72 64 20  125} If the 3rd 
39e0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
39f0: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
3a00: 20 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20   NULL then.**   
3a10: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
3a20: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 69  exec()] shall si
3a30: 6c 65 6e 74 6c 79 20 64 69 73 63 61 72 64 20 71  lently discard q
3a40: 75 65 72 79 20 72 65 73 75 6c 74 73 2e 0a 2a 2a  uery results..**
3a50: 0a 2a 2a 20 7b 48 31 32 31 33 31 7d 20 49 66 20  .** {H12131} If 
3a60: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
3a70: 77 68 69 6c 65 20 70 61 72 73 69 6e 67 20 6f 72  while parsing or
3a80: 20 65 76 61 6c 75 61 74 69 6e 67 20 61 6e 79 20   evaluating any 
3a90: 6f 66 20 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20  of the SQL.**   
3aa0: 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
3ab0: 73 20 69 6e 20 74 68 65 20 53 20 70 61 72 61 6d  s in the S param
3ac0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
3ad0: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3ae0: 5d 20 61 6e 64 20 69 66 0a 2a 2a 20 20 20 20 20  ] and if.**     
3af0: 20 20 20 20 20 74 68 65 20 45 20 70 61 72 61 6d       the E param
3b00: 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  eter is not NULL
3b10: 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  , then [sqlite3_
3b20: 65 78 65 63 28 29 5d 20 73 68 61 6c 6c 20 73 74  exec()] shall st
3b30: 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
3b40: 69 6e 20 2a 45 20 61 6e 20 61 70 70 72 6f 70 72  in *E an appropr
3b50: 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
3b60: 67 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ge written into 
3b70: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a  memory obtained.
3b80: 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
3b90: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
3ba0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ()]..**.** {H121
3bb0: 33 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  34} The [sqlite3
3bc0: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3bd0: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
3be0: 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66  set the value of
3bf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 45 20  .**          *E 
3c00: 74 6f 20 4e 55 4c 4c 20 69 66 20 45 20 69 73 20  to NULL if E is 
3c10: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 74 68 65  not NULL and the
3c20: 72 65 20 61 72 65 20 6e 6f 20 65 72 72 6f 72 73  re are no errors
3c30: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 37 7d  ..**.** {H12137}
3c40: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
3c50: 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 66  ec(D,S,C,A,E)] f
3c60: 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65  unction shall se
3c70: 74 20 74 68 65 20 5b 65 72 72 6f 72 20 63 6f 64  t the [error cod
3c80: 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  e].**          a
3c90: 6e 64 20 6d 65 73 73 61 67 65 20 61 63 63 65 73  nd message acces
3ca0: 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74  sible via [sqlit
3cb0: 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 0a  e3_errcode()], .
3cc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
3cd0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
3ce0: 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20  rcode()],.**    
3cf0: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
3d00: 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73  rrmsg()], and [s
3d10: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
3d20: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33  )]..**.** {H1213
3d30: 38 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61  8} If the S para
3d40: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
3d50: 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45  3_exec(D,S,C,A,E
3d60: 29 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  )] is NULL or an
3d70: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6d 70  .**          emp
3d80: 74 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e  ty string or con
3d90: 74 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74  tains nothing ot
3da0: 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70  her than whitesp
3db0: 61 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a  ace, comments,.*
3dc0: 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 2f 6f  *          and/o
3dd0: 72 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68  r semicolons, th
3de0: 65 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73  en results of [s
3df0: 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
3e00: 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
3e10: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
3e20: 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20  _errcode()],.** 
3e30: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3e40: 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e 64  3_errmsg()], and
3e50: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3e60: 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
3e70: 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 74 6f    shall reset to
3e80: 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72 72   indicate no err
3e90: 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ors..**.** ASSUM
3ea0: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
3eb0: 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73 74  12141} The first
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
3ed0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6d  qlite3_exec()] m
3ee0: 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64 20  ust be an valid 
3ef0: 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20 20  and open.**     
3f00: 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
3f10: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a  onnection]..**.*
3f20: 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 20 64  * {A12142} The d
3f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3f40: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 63  on must not be c
3f50: 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20 20  losed while.**  
3f60: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
3f70: 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e 6e  _exec()] is runn
3f80: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31  ing..**.** {A121
3f90: 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  43} The calling 
3fa0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
3fb0: 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  use [sqlite3_fre
3fc0: 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20  e()] to free.** 
3fd0: 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65 6d           the mem
3fe0: 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73 67  ory that *errmsg
3ff0: 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
4000: 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65 72  g at once the er
4010: 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ror.**          
4020: 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c 6f  message is no lo
4030: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a  nger needed..**.
4040: 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 65 20  ** {A12145} The 
4050: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
4060: 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70 61  xt in the 2nd pa
4070: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
4080: 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20 20  te3_exec()].**  
4090: 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 65 6d          must rem
40a0: 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77 68  ain unchanged wh
40b0: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ile [sqlite3_exe
40c0: 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  c()] is running.
40d0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
40e0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
40f0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4120: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4130: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4150: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4160: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4170: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4180: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4190: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
41a0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
41b0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
41c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
41f0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4200: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4210: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4230: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4240: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4250: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4260: 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31  Result Codes {H1
4270: 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  0210} <S10700>.*
4280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4290: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
42a0: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
42b0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
42c0: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
42d0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
42e0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
42f0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
4300: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
4310: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
4320: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
4330: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4340: 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f 72  cates success or
4350: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
4360: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
4370: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
4380: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
4390: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
43a0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
43b0: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
43c0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
43d0: 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  codes].*/.#defin
43e0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
43f0: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
4400: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
4410: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
4420: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
4430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4440: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
4450: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
4460: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
4470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4480: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
4490: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
44a0: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
44b0: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
44c0: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
44d0: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
44e0: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
44f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4500: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
4510: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
4520: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
4530: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4550: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
4560: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4570: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
4580: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4590: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
45a0: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
45b0: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
45c0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
45d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
45e0: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
45f0: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
4600: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4610: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
4620: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
4630: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
4640: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
4650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4660: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
4670: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
4680: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
4690: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
46a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46b0: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
46c0: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
46d0: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
46e0: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
46f0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
4700: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
4710: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
4720: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
4730: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
4740: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
4750: 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53    12   /* NOT US
4760: 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63  ED. Table or rec
4770: 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f  ord not found */
4780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4790: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
47a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
47b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
47c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
47d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
47f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4800: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4810: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4820: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
4830: 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55     15   /* NOT U
4840: 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f  SED. Database lo
4850: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f  ck protocol erro
4860: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4870: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20  ITE_EMPTY       
4880: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  16   /* Database
4890: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65   is empty */.#de
48a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45  fine SQLITE_SCHE
48b0: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20  MA      17   /* 
48c0: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  The database sch
48d0: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23  ema changed */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f  define SQLITE_TO
48f0: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f  OBIG      18   /
4900: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  * String or BLOB
4910: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69   exceeds size li
4920: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mit */.#define S
4930: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
4940: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20    19   /* Abort 
4950: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e  due to constrain
4960: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23  t violation */.#
4970: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4980: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f  SMATCH    20   /
4990: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d  * Data type mism
49a0: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20  atch */.#define 
49b0: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20  SQLITE_MISUSE   
49c0: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61     21   /* Libra
49d0: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63  ry used incorrec
49e0: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tly */.#define S
49f0: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20  QLITE_NOLFS     
4a00: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f    22   /* Uses O
4a10: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73  S features not s
4a20: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74  upported on host
4a30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a40: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32  TE_AUTH        2
4a50: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61  3   /* Authoriza
4a60: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  tion denied */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f  define SQLITE_FO
4a80: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f  RMAT      24   /
4a90: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61  * Auxiliary data
4aa0: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f  base format erro
4ab0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4ac0: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20  ITE_RANGE       
4ad0: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61  25   /* 2nd para
4ae0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4af0: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e  _bind out of ran
4b00: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge */.#define SQ
4b10: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20  LITE_NOTADB     
4b20: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70   26   /* File op
4b30: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74  ened that is not
4b40: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
4b50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b60: 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31  TE_ROW         1
4b70: 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  00  /* sqlite3_s
4b80: 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65  tep() has anothe
4b90: 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23  r row ready */.#
4ba0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f  define SQLITE_DO
4bb0: 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f  NE        101  /
4bc0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
4bd0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
4be0: 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e  ecuting */./* en
4bf0: 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  d-of-error-codes
4c00: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
4c10: 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65  REF: Extended Re
4c20: 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30 32  sult Codes {H102
4c30: 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20  20} <S10700>.** 
4c40: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c50: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
4c60: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4c70: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
4c80: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4c90: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
4ca0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4cb0: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
4cc0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
4cd0: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
4ce0: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
4cf0: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
4d00: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
4d10: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
4d20: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4d30: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4d40: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4d50: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4d60: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4d70: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4d80: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
4d90: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
4da0: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
4db0: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
4dc0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
4dd0: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
4de0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
4df0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
4e00: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
4e10: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
4e20: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
4e30: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
4e40: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
4e50: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
4e60: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
4e70: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
4e80: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
4e90: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
4ea0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
4eb0: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
4ec0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
4ed0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4ee0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
4ef0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4f00: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
4f10: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
4f20: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
4f30: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
4f40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f50: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
4f60: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
4f70: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
4f80: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f90: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
4fa0: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
4fb0: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4fc0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4fd0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4fe0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
4ff0: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
5000: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
5010: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
5020: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
5030: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
5040: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
5050: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
5060: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
5070: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2a  exactly zero..**
5080: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
5090: 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d 20 54  **.** {H10223} T
50a0: 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
50b0: 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65 64   for an extended
50c0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68 61   result code sha
50d0: 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  ll contains.**  
50e0: 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74 65          a relate
50f0: 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c 74  d primary result
5100: 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66 69   code as a prefi
5110: 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 34  x..**.** {H10224
5120: 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c 74  } Primary result
5130: 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c   code names shal
5140: 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67  l contain a sing
5150: 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65 72  le "_" character
5160: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 35 7d  ..**.** {H10225}
5170: 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   Extended result
5180: 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61 6c   code names shal
5190: 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f 72  l contain two or
51a0: 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61 63   more "_" charac
51b0: 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ters..**.** {H10
51c0: 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69 63  226} The numeric
51d0: 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78 74   value of an ext
51e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
51f0: 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20  e shall contain 
5200: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
5210: 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66  numeric value of
5220: 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64 69   its correspondi
5230: 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c  ng primary resul
5240: 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20 20  t code in.**    
5250: 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74 20        its least 
5260: 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62 69  significant 8 bi
5270: 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ts..*/.#define S
5280: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
5290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
52a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
52b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
52d0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
52e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
52f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5300: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
5310: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5320: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
5330: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5340: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
5350: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5360: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
5390: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
53b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53c0: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
53d0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
53e0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
53f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5400: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
5410: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5420: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
5430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5440: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5450: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5460: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5480: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5490: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54a0: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
54b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54c0: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
54d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
54e0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
54f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5500: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
5510: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5520: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5540: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5560: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5580: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5590: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55a0: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
55b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55c0: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
55d0: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
55e0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
55f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5600: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
5610: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5620: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 0a 2f  RR | (15<<8))../
5630: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
5640: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
5650: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b 48  en Operations {H
5660: 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e 20  10230} <H11120> 
5670: 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12700>.**.** T
5680: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
5690: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
56a0: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
56b0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
56c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
56d0: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
56e0: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
56f0: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
5700: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
5710: 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d of the.** [sql
5720: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
5730: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5740: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
5750: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
5760: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
5770: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
5780: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
5790: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
57a0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
57b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
57c0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
57d0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
57e0: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
57f0: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c  0008.#define SQL
5800: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
5810: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
5820: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
5830: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
5840: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5850: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
5860: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
5870: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5880: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
5890: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
58a0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
58b0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
58c0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
58d0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
58e0: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0800.#define SQL
58f0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
5900: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5910: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
5920: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
5930: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
5940: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  2000.#define SQL
5950: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
5960: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
5970: 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  4000.#define SQL
5980: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
5990: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
59a0: 38 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  8000.#define SQL
59b0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
59c0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
59d0: 30 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0000../*.** CAPI
59e0: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
59f0: 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48 31  racteristics {H1
5a00: 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a 2a  0240} <H11120>.*
5a10: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5a20: 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65 74  Capabilities met
5a30: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
5a40: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
5a50: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
5a60: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
5a70: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5a80: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5a90: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5aa0: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5ab0: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5ac0: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5ad0: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5ae0: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5af0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5b00: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5b10: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
5b20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5b30: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
5b40: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
5b50: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
5b60: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
5b70: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5b80: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5b90: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5ba0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5bb0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5bc0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5bd0: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5be0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5bf0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5c00: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5c10: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
5c20: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5c30: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
5c40: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
5c50: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
5c60: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
5c70: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5c80: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5c90: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5ca0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5cb0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5cc0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5cd0: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5ce0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5cf0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5d00: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5d10: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
5d20: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
5d30: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
5d40: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
5d50: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
5d60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5d70: 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30 30  IC          0x00
5d80: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5d90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5da0: 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30 30  IC512       0x00
5db0: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  000002.#define S
5dc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5dd0: 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC1K        0x00
5de0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
5df0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e00: 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC2K        0x00
5e10: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
5e20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e30: 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC4K        0x00
5e40: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5e50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e60: 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30 30  IC8K        0x00
5e70: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
5e80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5e90: 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30 30  IC16K       0x00
5ea0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
5eb0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ec0: 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30 30  IC32K       0x00
5ed0: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
5ee0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ef0: 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30 30  IC64K       0x00
5f00: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
5f10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5f20: 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30 30  _APPEND     0x00
5f30: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53  000200.#define S
5f40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
5f50: 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30 30  ENTIAL      0x00
5f60: 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  000400../*.** CA
5f70: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
5f80: 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31 30  king Levels {H10
5f90: 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c 48  250} <H11120> <H
5fa0: 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  11310>.**.** SQL
5fb0: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
5fc0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
5fd0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
5fe0: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
5ff0: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
6000: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
6010: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
6020: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
6030: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6040: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
6050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6060: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
6070: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
6080: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
6090: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
60a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
60b0: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
60c0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
60d0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
60e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
60f0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
6100: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
6110: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
6120: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20 7b  ion Type Flags {
6130: 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30 3e  H10260} <H11120>
6140: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
6150: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
6160: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
6170: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6180: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6190: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
61a0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
61b0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
61c0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
61d0: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
61e0: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
61f0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6200: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
6210: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
6220: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
6230: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
6240: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
6250: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
6260: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
6270: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
6280: 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49 54  ushed. The SQLIT
6290: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66 6c  E_SYNC_NORMAL fl
62a0: 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75  ag means.** to u
62b0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
62c0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68 65  ) semantics. The
62d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
62e0: 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20  L flag means.** 
62f0: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
6300: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
6310: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
6320: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
6330: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6340: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
6350: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6360: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
6370: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
6380: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
6390: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
63a0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
63b0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
63c0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
63d0: 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32 30  le {H11110} <S20
63e0: 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73  110>.**.** An [s
63f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6400: 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
6410: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74  n open file in t
6420: 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66 61  he OS.** interfa
6430: 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69 76  ce layer.  Indiv
6440: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
6450: 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ce implementatio
6460: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
6470: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
6480: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
6490: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
64a0: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
64b0: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
64c0: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
64d0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
64e0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
64f0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6500: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
6510: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
6520: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
6530: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
6540: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
6550: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
6560: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
6570: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
6580: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
6590: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
65a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
65b0: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
65c0: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
65d0: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
65e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
65f0: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
6600: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
6610: 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30 7d   Object {H11120}
6620: 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S20110>.**.** 
6630: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
6640: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
6650: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74  3_vfs] xOpen met
6660: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
6670: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
6680: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
6690: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
66a0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
66b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
66c0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
66d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
66e0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
66f0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
6700: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
6710: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
6720: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
6730: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
6740: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
6750: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
6760: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
6770: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
6780: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
6790: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
67a0: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
67b0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
67c0: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
67d0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
67e0: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
67f0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
6800: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
6810: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
6820: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
6830: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
6840: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
6850: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
6860: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
6870: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
6880: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
6890: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
68a0: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
68b0: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
68c0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
68d0: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
68e0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
68f0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
6900: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6910: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
6920: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
6930: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
6940: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
6950: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
6960: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
6970: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
6980: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
6990: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
69a0: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
69b0: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
69c0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
69d0: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
69e0: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
69f0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
6a00: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
6a10: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
6a20: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
6a30: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
6a40: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
6a50: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
6a60: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
6a70: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
6a80: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
6a90: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
6aa0: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
6ab0: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
6ac0: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
6ad0: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
6ae0: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
6af0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
6b00: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
6b10: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
6b20: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
6b30: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
6b40: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
6b50: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
6b60: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
6b70: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
6b80: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
6b90: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
6ba0: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
6bb0: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
6bc0: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
6bd0: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
6be0: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
6bf0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
6c00: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
6c10: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
6c20: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
6c30: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
6c40: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
6c50: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
6c60: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
6c70: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
6c80: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
6c90: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
6ca0: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
6cb0: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
6cc0: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
6cd0: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
6ce0: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
6cf0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
6d00: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
6d10: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
6d20: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
6d30: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
6d40: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
6d50: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
6d60: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
6d70: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
6d80: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
6d90: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53  own use..** A [S
6da0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
6db0: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20  STATE | list of 
6dc0: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
6dd0: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
6de0: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
6df0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
6e00: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
6e10: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
6e20: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
6e30: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
6e40: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
6e50: 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nflicts..**.** T
6e60: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
6e70: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6e80: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
6e90: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
6ea0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
6eb0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
6ec0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
6ed0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
6ee0: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
6ef0: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
6f00: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
6f10: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
6f20: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
6f30: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
6f40: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
6f50: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
6f60: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
6f70: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
6f80: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
6f90: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
6fa0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
6fb0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
6fc0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6fd0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
6fe0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6ff0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
7000: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7010: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
7020: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7030: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
7040: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7050: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
7060: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7070: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
7080: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7090: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
70a0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
70b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
70c0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
70d0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
70e0: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
70f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
7100: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  UENTIAL].** </ul
7110: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  >.**.** The SQLI
7120: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
7130: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
7140: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
7150: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
7160: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
7170: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7180: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
7190: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
71a0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
71b0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
71c0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
71d0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
71e0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
71f0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
7200: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
7210: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
7220: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
7230: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
7240: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
7250: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
7260: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
7270: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
7280: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
7290: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
72a0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
72b0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
72c0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
72d0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
72e0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
72f0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
7300: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
7310: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
7320: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
7330: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
7340: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a  * to xWrite()..*
7350: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20  *.** If xRead() 
7360: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49  returns SQLITE_I
7370: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
7380: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c  it must also fil
7390: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65  l.** in the unre
73a0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74  ad portions of t
73b0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a  he buffer with z
73c0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61  eros.  A VFS tha
73d0: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65  t.** fails to ze
73e0: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65  ro-fill short re
73f0: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74  ads might seem t
7400: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72  o work.  However
7410: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20  ,.** failure to 
7420: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
7430: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74  reads will event
7440: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a  ually lead to.**
7450: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
7460: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  tion..*/.typedef
7470: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7480: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  io_methods sqlit
7490: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73  e3_io_methods;.s
74a0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
74b0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
74c0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
74d0: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
74e0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
74f0: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65   (*xRead)(sqlite
7500: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20  3_file*, void*, 
7510: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
7520: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
7530: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28    int (*xWrite)(
7540: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63  sqlite3_file*, c
7550: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
7560: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
7570: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
7580: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73  t (*xTruncate)(s
7590: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
75a0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65  lite3_int64 size
75b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
75c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
75d0: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69   int flags);.  i
75e0: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28  nt (*xFileSize)(
75f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
7600: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53  qlite3_int64 *pS
7610: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c  ize);.  int (*xL
7620: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
7630: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
7640: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74  (*xUnlock)(sqlit
7650: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
7660: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65    int (*xCheckRe
7670: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69  servedLock)(sqli
7680: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a  te3_file*, int *
7690: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
76a0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28  (*xFileControl)(
76b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
76c0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72  nt op, void *pAr
76d0: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63  g);.  int (*xSec
76e0: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33  torSize)(sqlite3
76f0: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
7700: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65  *xDeviceCharacte
7710: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33  ristics)(sqlite3
7720: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64  _file*);.  /* Ad
7730: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
7740: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
7750: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
7760: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
7770: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
7780: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
7790: 63 6f 64 65 73 20 7b 48 31 31 33 31 30 7d 20 3c  codes {H11310} <
77a0: 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30800>.**.** Th
77b0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
77c0: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
77d0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
77e0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
77f0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
7800: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7810: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
7820: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7830: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
7840: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
7850: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
7860: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
7870: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
7880: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
7890: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
78a0: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
78b0: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
78c0: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
78d0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
78e0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
78f0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
7900: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7910: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
7920: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
7930: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
7940: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
7950: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
7960: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
7970: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
7980: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
7990: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
79a0: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
79b0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
79c0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
79d0: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
79e0: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
79f0: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
7a00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7a10: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
7a20: 20 20 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a          1../*.**
7a30: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
7a40: 20 48 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d   Handle {H17110}
7a50: 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20   <S20130>.**.** 
7a60: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
7a70: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
7a80: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
7a90: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
7aa0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
7ab0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
7ac0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
7ad0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
7ae0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
7af0: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
7b00: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
7b10: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
7b20: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
7b30: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
7b40: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
7b50: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7b60: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
7b70: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
7b80: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
7b90: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
7ba0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
7bb0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
7bc0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7bd0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7be0: 4f 62 6a 65 63 74 20 7b 48 31 31 31 34 30 7d 20  Object {H11140} 
7bf0: 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S20100>.**.** A
7c00: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
7c10: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
7c20: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
7c30: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
7c40: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
7c50: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
7c60: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
7c70: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
7c80: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
7c90: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
7ca0: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
7cb0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
7cc0: 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  em"..**.** The v
7cd0: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
7ce0: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
7cf0: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
7d00: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
7d10: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
7d20: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
7d30: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
7d40: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
7d50: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
7d60: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
7d70: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
7d80: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
7d90: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
7da0: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
7db0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
7dc0: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
7dd0: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
7de0: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
7df0: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
7e00: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
7e10: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
7e20: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
7e30: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
7e40: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
7e50: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
7e60: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
7e70: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
7e80: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
7e90: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
7ea0: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
7eb0: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
7ec0: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
7ed0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
7ee0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
7ef0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
7f00: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
7f10: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
7f20: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
7f30: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
7f40: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
7f50: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
7f60: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
7f70: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
7f80: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
7f90: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
7fa0: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
7fb0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
7fc0: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
7fd0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
7fe0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
7ff0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
8000: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
8010: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
8020: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
8030: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
8040: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
8050: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
8060: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
8070: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
8080: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
8090: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
80a0: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
80b0: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
80c0: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
80d0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
80e0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
80f0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
8100: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
8110: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
8120: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
8130: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
8140: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
8150: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
8160: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
8170: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
8180: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
8190: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
81a0: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
81b0: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
81c0: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
81d0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
81e0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 31 7d  ..**.** {H11141}
81f0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61   SQLite will gua
8200: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 65 20  rantee that the 
8210: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
8220: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
8230: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
8240: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
8250: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
8260: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
8270: 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72  e().  SQLite fur
8280: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
8290: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
82a0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
82b0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
82c0: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
82d0: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 7b 45 4e 44  .** called. {END
82e0: 7d 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  }  Because of th
82f0: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
8300: 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nse,.** the [sql
8310: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
8320: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
8330: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
8340: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
8350: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
8360: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
8370: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
8380: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
8390: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
83a0: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
83b0: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
83c0: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69 74  en.** must invit
83d0: 65 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  e its own tempor
83e0: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
83f0: 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72   file.  Whenever
8400: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
8410: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
8420: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
8430: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
8440: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
8450: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
8460: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
8470: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8480: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34  E]..**.** {H1114
8490: 32 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  2} The flags arg
84a0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
84b0: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
84c0: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
84d0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
84e0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
84f0: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
8500: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
8510: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
8520: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
8530: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
8540: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
8550: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
8560: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
8570: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
8580: 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f  . {END}.** If xO
8590: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
85a0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
85b0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
85c0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
85d0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
85e0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
85f0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
8600: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
8610: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 33 7d 20  .**.** {H11143} 
8620: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
8630: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
8640: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
8650: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
8660: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
8670: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
8680: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
8690: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
86a0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
86b0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
86c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
86d0: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
86e0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
86f0: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
8700: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8710: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
8720: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8730: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
8740: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
8750: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
8760: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
8770: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
8780: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f  R_JOURNAL].** </
8790: 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ul> {END}.**.** 
87a0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
87b0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
87c0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
87d0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
87e0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
87f0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
8800: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
8810: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
8820: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
8830: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
8840: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
8850: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
8860: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
8870: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
8880: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
8890: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
88a0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
88b0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
88c0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
88d0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
88e0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
88f0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
8900: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
8910: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
8920: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
8930: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
8940: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
8950: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
8960: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
8970: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
8980: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
8990: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
89a0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
89b0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
89c0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
89d0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
89e0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
89f0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
8a00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
8a10: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8a20: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
8a30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
8a40: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
8a50: 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 35 7d  >.**.** {H11145}
8a60: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
8a70: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8a80: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
8a90: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
8aa0: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
8ab0: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 48  t is closed.  {H
8ac0: 31 31 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49  11146} The [SQLI
8ad0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8ae0: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
8af0: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20  e set for TEMP  
8b00: 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e  databases, journ
8b10: 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a  als and for subj
8b20: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ournals..**.** {
8b30: 48 31 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c  H11147} The [SQL
8b40: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8b50: 56 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  VE] flag means t
8b60: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
8b70: 65 20 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20  e opened.** for 
8b80: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8b90: 2e 20 20 54 68 69 73 20 66 6c 61 67 20 69 73 20  .  This flag is 
8ba0: 73 65 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65  set for all file
8bb0: 73 20 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20  s except.** for 
8bc0: 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
8bd0: 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e file..**.** {H
8be0: 31 31 31 34 38 7d 20 41 74 20 6c 65 61 73 74 20  11148} At least 
8bf0: 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
8c00: 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
8c10: 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
8c20: 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
8c30: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
8c40: 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
8c50: 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
8c60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
8c70: 65 6e 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 78  en. {END}  The x
8c80: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
8c90: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
8ca0: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
8cb0: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
8cc0: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
8cd0: 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 39  n..**.** {H11149
8ce0: 7d 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  } The flags argu
8cf0: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
8d00: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
8d10: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
8d20: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
8d30: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
8d40: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
8d50: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
8d60: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
8d70: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
8d80: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
8d90: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
8da0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
8db0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
8dc0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
8dd0: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
8de0: 20 7b 45 4e 44 7d 20 20 54 68 65 20 66 69 6c 65   {END}  The file
8df0: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
8e00: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ectory..**.** {H
8e10: 31 31 31 35 30 7d 20 53 51 4c 69 74 65 20 77 69  11150} SQLite wi
8e20: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
8e30: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
8e40: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
8e50: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
8e60: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
8e70: 68 6e 61 6d 65 2e 20 7b 48 31 31 31 35 31 7d 20  hname. {H11151} 
8e80: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
8e90: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
8ea0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
8eb0: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
8ec0: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
8ed0: 74 68 6f 64 73 2e 20 7b 45 4e 44 7d 20 20 49 66  thods. {END}  If
8ee0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
8ef0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
8f00: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
8f10: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
8f20: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
8f30: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
8f40: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
8f50: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
8f60: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
8f70: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
8f80: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
8f90: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
8fa0: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
8fb0: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
8fc0: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
8fd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
8fe0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
8ff0: 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  p(), and xCurren
9000: 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63  tTime() interfac
9010: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74  es.** are not st
9020: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
9030: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
9040: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
9050: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
9060: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
9070: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
9080: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
9090: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
90a0: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
90b0: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
90c0: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
90d0: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
90e0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
90f0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
9100: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
9110: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
9120: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
9130: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
9140: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
9150: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
9160: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
9170: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
9180: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
9190: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
91a0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
91b0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
91c0: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
91d0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
91e0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
91f0: 64 20 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64  d time..*/.typed
9200: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
9210: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
9220: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
9230: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
9240: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
9250: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
9260: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a  version number *
9270: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
9280: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
9290: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
92a0: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
92b0: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
92c0: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
92d0: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
92e0: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
92f0: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
9300: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
9310: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
9320: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
9330: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
9340: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
9350: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
9360: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
9370: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
9380: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
9390: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
93a0: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
93b0: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
93c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
93d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
93e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
93f0: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
9400: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
9410: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
9420: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
9430: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
9440: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
9450: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
9460: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
9470: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
9480: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
9490: 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  ags, int *pResOu
94a0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
94b0: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
94c0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
94d0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
94e0: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
94f0: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
9500: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
9510: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9520: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
9530: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
9540: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
9550: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
9560: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a  rrMsg);.  void *
9570: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
9580: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
9590: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
95a0: 6c 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  l);.  void (*xDl
95b0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
95c0: 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
95d0: 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
95e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
95f0: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
9600: 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
9610: 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
9620: 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
9630: 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
9640: 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
9650: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
9660: 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ble*);.  int (*x
9670: 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
9680: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
9690: 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e   char *);.  /* N
96a0: 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
96b0: 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67   appended in fig
96c0: 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
96d0: 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
96e0: 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
96f0: 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
9700: 68 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a  his happens. */.
9710: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
9720: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
9730: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
9740: 74 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48  thod {H11190} <H
9750: 31 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31  11140>.**.** {H1
9760: 31 31 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65  1191} These inte
9770: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
9780: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
9790: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
97a0: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
97b0: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
97c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
97d0: 6a 65 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65  ject. {END}  The
97e0: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
97f0: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
9800: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
9810: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
9820: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 7b 48  oking for..** {H
9830: 31 31 31 39 32 7d 20 57 69 74 68 20 53 51 4c 49  11192} With SQLI
9840: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
9850: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
9860: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
9870: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
9880: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
9890: 2a 20 7b 48 31 31 31 39 33 7d 20 57 69 74 68 20  * {H11193} With 
98a0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
98b0: 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
98c0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
98d0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
98e0: 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72  e file is both r
98f0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
9900: 61 62 6c 65 2e 0a 2a 2a 20 7b 48 31 31 31 39 34  able..** {H11194
9910: 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  } With SQLITE_AC
9920: 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
9930: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
9940: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
9950: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
9960: 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  able..*/.#define
9970: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
9980: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
9990: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
99a0: 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65  _READWRITE 1.#de
99b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
99c0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a  SS_READ      2..
99d0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
99e0: 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53  Initialize The S
99f0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48  QLite Library {H
9a00: 31 30 31 33 30 7d 20 3c 53 32 30 30 30 30 3e 3c  10130} <S20000><
9a10: 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S30100>.**.** Th
9a20: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9a30: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
9a40: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
9a50: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
9a60: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
9a70: 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
9a80: 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
9a90: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
9aa0: 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
9ab0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
9ac0: 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a  itialize()..**.*
9ad0: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
9ae0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9af0: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
9b00: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
9b10: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69  .** the first ti
9b20: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
9b30: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
9b40: 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ed during the li
9b50: 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65  fetime of.** the
9b60: 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
9b70: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  it is the first 
9b80: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
9b90: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
9ba0: 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  oked.** followin
9bb0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  g a call to sqli
9bc0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
9bd0: 20 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69   Only an effecti
9be0: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
9bf0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9c00: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
9c10: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
9c20: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
9c30: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
9c40: 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  ops..**.** Among
9c50: 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73   other things, s
9c60: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9c70: 65 28 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65  e() shall invoke
9c80: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
9c90: 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c  nit().  Similarl
9ca0: 79 2c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y, sqlite3_shutd
9cb0: 6f 77 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69  own().** shall i
9cc0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73  nvoke sqlite3_os
9cd0: 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  _end()..**.** Th
9ce0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9cf0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
9d00: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
9d10: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
9d20: 2a 20 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65  * If for some re
9d30: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
9d40: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
9d50: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
9d60: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
9d70: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
9d80: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
9d90: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
9da0: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
9db0: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
9dc0: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
9dd0: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
9de0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
9df0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
9e00: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
9e10: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
9e20: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
9e30: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
9e40: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
9e50: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
9e60: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
9e70: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
9e80: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
9e90: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
9ea0: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
9eb0: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
9ec0: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
9ed0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9ee0: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
9ef0: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
9f00: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
9f10: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
9f20: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
9f30: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
9f40: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
9f50: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
9f60: 65 61 64 79 2e 20 20 48 6f 77 65 76 65 72 2c 20  eady.  However, 
9f70: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
9f80: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
9f90: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
9fa0: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
9fb0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
9fc0: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
9fd0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
9fe0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
9ff0: 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
a000: 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
a010: 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
a020: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a030: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
a040: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
a050: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
a060: 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
a070: 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
a080: 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
a090: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
a0a0: 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
a0b0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
a0c0: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
a0d0: 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
a0e0: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
a0f0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
a100: 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
a110: 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
a120: 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
a130: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
a140: 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
a150: 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
a160: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
a170: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
a180: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
a190: 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
a1a0: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
a1b0: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
a1c0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
a1d0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
a1e0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
a1f0: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
a200: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
a210: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
a220: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
a230: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
a240: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
a250: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
a260: 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
a270: 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
a280: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
a290: 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
a2a0: 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
a2b0: 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
a2c0: 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
a2d0: 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
a2e0: 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
a2f0: 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
a300: 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
a310: 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
a320: 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
a330: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
a340: 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
a350: 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
a360: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
a370: 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
a380: 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
a390: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
a3a0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
a3b0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
a3c0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
a3d0: 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
a3e0: 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
a3f0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
a400: 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
a410: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
a420: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
a430: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a440: 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
a450: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
a460: 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
a470: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
a480: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
a490: 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
a4a0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
a4b0: 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
a4c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
a4d0: 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
a4e0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
a4f0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
a500: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
a510: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
a520: 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
a530: 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
a540: 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75 6e 69  compiled for uni
a550: 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72 20 6f  x, windows, or o
a560: 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62 75 69  s/2..** When bui
a570: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
a580: 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20 74 68  tforms (using th
a590: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
a5a0: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
a5b0: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
a5c0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
a5d0: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
a5e0: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
a5f0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
a600: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
a610: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a620: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
a630: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
a640: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
a650: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a660: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
a670: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
a680: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
a690: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
a6a0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
a6b0: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
a6c0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
a6d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a6e0: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
a6f0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a700: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
a710: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
a720: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
a730: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
a740: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
a750: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
a760: 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 34  ite Library {H14
a770: 31 30 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33  100} <S20000><S3
a780: 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0200>.** EXPERIM
a790: 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ENTAL.**.** The 
a7a0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a7b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
a7c0: 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
a7d0: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
a7e0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
a7f0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
a800: 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
a810: 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
a820: 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
a830: 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
a840: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
a850: 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
a860: 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
a870: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
a880: 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
a890: 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
a8a0: 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
a8b0: 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
a8c0: 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
a8d0: 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
a8e0: 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
a8f0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
a900: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
a910: 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
a920: 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
a930: 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
a940: 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
a950: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
a960: 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
a970: 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
a980: 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
a990: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
a9a0: 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
a9b0: 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
a9c0: 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
a9d0: 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
a9e0: 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
a9f0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
aa00: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
aa10: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
aa20: 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
aa30: 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
aa40: 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f  utdown()]..** No
aa50: 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
aa60: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
aa70: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
aa80: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
aa90: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
aaa0: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
aab0: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
aac0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
aad0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
aae0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
aaf0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
ab00: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
ab10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
ab20: 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e  NGLETHREAD | con
ab30: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ab40: 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
ab50: 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
ab60: 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
ab70: 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
ab80: 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
ab90: 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
aba0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
abb0: 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
abc0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
abd0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
abe0: 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
abf0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
ac00: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e  **.** When a con
ac10: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ac20: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
ac30: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
ac40: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
ac50: 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  ** If the option
ac60: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
ac70: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
ac80: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
ac90: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
aca0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
acb0: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
acc0: 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e   code]..**.** IN
acd0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
ace0: 7b 48 31 34 31 30 33 7d 20 41 20 73 75 63 63 65  {H14103} A succe
acf0: 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
ad00: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   of [sqlite3_con
ad10: 66 69 67 28 29 5d 20 73 68 61 6c 6c 20 72 65 74  fig()] shall ret
ad20: 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
ad30: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
ad40: 2a 2a 20 7b 48 31 34 31 30 36 7d 20 54 68 65 20  ** {H14106} The 
ad50: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ad60: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
ad70: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
ad80: 45 5f 4d 49 53 55 53 45 5d 0a 2a 2a 20 20 20 20  E_MISUSE].**    
ad90: 20 20 20 20 20 20 69 66 20 69 74 20 69 73 20 69        if it is i
ada0: 6e 76 6f 6b 65 64 20 69 6e 20 62 65 74 77 65 65  nvoked in betwee
adb0: 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
adc0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
add0: 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
ade0: 20 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64    [sqlite3_shutd
adf0: 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  own()]..**.** {H
ae00: 31 34 31 32 30 7d 20 41 20 73 75 63 63 65 73 73  14120} A success
ae10: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
ae20: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
ae30: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
ae40: 4c 45 54 48 52 45 41 44 5d 29 0a 2a 2a 20 20 20  LETHREAD]).**   
ae50: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65 74         shall set
ae60: 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68   the default [th
ae70: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
ae80: 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 0a   Single-thread..
ae90: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 33 7d 20 41  **.** {H14123} A
aea0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
aeb0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
aec0: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
aed0: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
aee0: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ).**          sh
aef0: 61 6c 6c 20 73 65 74 20 74 68 65 20 64 65 66 61  all set the defa
af00: 75 6c 74 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ult [threading m
af10: 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
af20: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  read..**.** {H14
af30: 31 32 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  126} A successfu
af40: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
af50: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
af60: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
af70: 49 5a 45 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20  IZED]).**       
af80: 20 20 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65     shall set the
af90: 20 64 65 66 61 75 6c 74 20 5b 74 68 72 65 61 64   default [thread
afa0: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
afb0: 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  ialized..**.** {
afc0: 48 31 34 31 32 39 7d 20 41 20 73 75 63 63 65 73  H14129} A succes
afd0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
afe0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
aff0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
b000: 45 58 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 20 20  EX],X).**       
b010: 20 20 20 77 68 65 72 65 20 58 20 69 73 20 61 20     where X is a 
b020: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
b030: 69 74 69 61 6c 69 7a 65 64 20 5b 73 71 6c 69 74  itialized [sqlit
b040: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
b050: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  ].**          ob
b060: 6a 65 63 74 20 73 68 61 6c 6c 20 63 61 75 73 65  ject shall cause
b070: 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
b080: 6d 75 74 65 78 20 6f 70 65 72 61 74 69 6f 6e 73  mutex operations
b090: 20 70 65 72 66 6f 72 6d 65 64 0a 2a 2a 20 20 20   performed.**   
b0a0: 20 20 20 20 20 20 20 62 79 20 53 51 4c 69 74 65         by SQLite
b0b0: 20 74 6f 20 75 73 65 20 74 68 65 20 6d 75 74 65   to use the mute
b0c0: 78 20 6d 65 74 68 6f 64 73 20 74 68 61 74 20 77  x methods that w
b0d0: 65 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20 58  ere present in X
b0e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75 72  .**          dur
b0f0: 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  ing the call to 
b100: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
b110: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 33  )]..**.** {H1413
b120: 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  2} A successful 
b130: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
b140: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
b150: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
b160: 5d 2c 58 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  ],X).**         
b170: 20 77 68 65 72 65 20 58 20 69 73 20 61 20 70 6f   where X is a po
b180: 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c  inter to an [sql
b190: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
b1a0: 64 73 5d 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 20  ds] object .**  
b1b0: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 6f 76          shall ov
b1c0: 65 72 77 72 69 74 65 20 74 68 65 20 63 6f 6e 74  erwrite the cont
b1d0: 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ent of [sqlite3_
b1e0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 6f  mutex_methods] o
b1f0: 62 6a 65 63 74 0a 2a 2a 20 20 20 20 20 20 20 20  bject.**        
b200: 20 20 77 69 74 68 20 74 68 65 20 6d 75 74 65 78    with the mutex
b210: 20 6d 65 74 68 6f 64 73 20 63 75 72 72 65 6e 74   methods current
b220: 6c 79 20 69 6e 20 75 73 65 20 62 79 20 53 51 4c  ly in use by SQL
b230: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31  ite..**.** {H141
b240: 33 35 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  35} A successful
b250: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
b260: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
b270: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
b280: 2c 4d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ,M).**          
b290: 77 68 65 72 65 20 4d 20 69 73 20 61 20 70 6f 69  where M is a poi
b2a0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 69 74 69  nter to an initi
b2b0: 61 6c 69 7a 65 64 20 5b 73 71 6c 69 74 65 33 5f  alized [sqlite3_
b2c0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
b2d0: 20 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20           object 
b2e0: 73 68 61 6c 6c 20 63 61 75 73 65 20 61 6c 6c 20  shall cause all 
b2f0: 73 75 62 73 65 71 75 65 6e 74 20 6d 65 6d 6f 72  subsequent memor
b300: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 70 65  y allocation ope
b310: 72 61 74 69 6f 6e 73 0a 2a 2a 20 20 20 20 20 20  rations.**      
b320: 20 20 20 20 70 65 72 66 6f 72 6d 65 64 20 62 79      performed by
b330: 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 74   SQLite to use t
b340: 68 65 20 6d 65 74 68 6f 64 73 20 74 68 61 74 20  he methods that 
b350: 77 65 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20  were present in 
b360: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20 64  .**          M d
b370: 75 72 69 6e 67 20 74 68 65 20 63 61 6c 6c 20 74  uring the call t
b380: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b390: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  g()]..**.** {H14
b3a0: 31 33 38 7d 20 41 20 73 75 63 63 65 73 73 66 75  138} A successfu
b3b0: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
b3c0: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b3d0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
b3e0: 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20 20 20 20 20  LOC],M).**      
b3f0: 20 20 20 20 77 68 65 72 65 20 4d 20 69 73 20 61      where M is a
b400: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
b410: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
b420: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 73 68 61 6c  ods] object shal
b430: 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76  l.**          ov
b440: 65 72 77 72 69 74 65 20 74 68 65 20 63 6f 6e 74  erwrite the cont
b450: 65 6e 74 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ent of [sqlite3_
b460: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  mem_methods] obj
b470: 65 63 74 20 77 69 74 68 20 0a 2a 2a 20 20 20 20  ect with .**    
b480: 20 20 20 20 20 20 74 68 65 20 6d 65 6d 6f 72 79        the memory
b490: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6d 65 74 68   allocation meth
b4a0: 6f 64 73 20 63 75 72 72 65 6e 74 6c 79 20 69 6e  ods currently in
b4b0: 20 75 73 65 20 62 79 0a 2a 2a 20 20 20 20 20 20   use by.**      
b4c0: 20 20 20 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a      SQLite..**.*
b4d0: 2a 20 7b 48 31 34 31 34 31 7d 20 41 20 73 75 63  * {H14141} A suc
b4e0: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
b4f0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
b500: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
b510: 4d 45 4d 53 54 41 54 55 53 5d 2c 31 29 0a 2a 2a  MEMSTATUS],1).**
b520: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
b530: 65 6e 61 62 6c 65 20 74 68 65 20 6d 65 6d 6f 72  enable the memor
b540: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
b550: 74 75 73 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6c  tus collection l
b560: 6f 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  ogic..**.** {H14
b570: 31 34 34 7d 20 41 20 73 75 63 63 65 73 73 66 75  144} A successfu
b580: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
b590: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b5a0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
b5b0: 54 55 53 5d 2c 30 29 0a 2a 2a 20 20 20 20 20 20  TUS],0).**      
b5c0: 20 20 20 20 73 68 61 6c 6c 20 64 69 73 61 62 6c      shall disabl
b5d0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
b5e0: 6f 63 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63  ocation status c
b5f0: 6f 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 2e  ollection logic.
b600: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 37 7d 20  .**.** {H14147} 
b610: 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
b620: 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63 6f 6c  ation status col
b630: 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 20 73 68  lection logic sh
b640: 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20 20 20 20  all be.**       
b650: 20 20 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65     enabled by de
b660: 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fault..**.** {H1
b670: 34 31 35 30 7d 20 41 20 73 75 63 63 65 73 73 66  4150} A successf
b680: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
b690: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
b6a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
b6b0: 43 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20  CH],S,Z,N).**   
b6c0: 20 20 20 20 20 20 20 77 68 65 72 65 20 5a 20 61         where Z a
b6d0: 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65 67  nd N are non-neg
b6e0: 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 20 61  ative integers a
b6f0: 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nd .**          
b700: 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  S is a pointer t
b710: 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d 65 6d  o an aligned mem
b720: 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 20 6c  ory buffer not l
b730: 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  ess than.**     
b740: 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73 20 69       Z*N bytes i
b750: 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63 61 75  n size shall cau
b760: 73 65 20 53 20 74 6f 20 62 65 20 75 73 65 64 20  se S to be used 
b770: 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
b780: 20 20 20 5b 73 63 72 61 74 63 68 20 6d 65 6d 6f     [scratch memo
b790: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f  ry allocator] fo
b7a0: 72 20 61 73 20 6d 61 6e 79 20 61 73 20 4e 20 73  r as many as N s
b7b0: 69 6d 75 6c 61 74 61 6e 65 6f 75 73 0a 2a 2a 20  imulataneous.** 
b7c0: 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74           allocat
b7d0: 69 6f 6e 73 20 65 61 63 68 20 6f 66 20 73 69 7a  ions each of siz
b7e0: 65 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31  e Z..**.** {H141
b7f0: 35 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  53} A successful
b800: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
b810: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
b820: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
b830: 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20  ],S,Z,N).**     
b840: 20 20 20 20 20 77 68 65 72 65 20 53 20 69 73 20       where S is 
b850: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  a NULL pointer s
b860: 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65  hall disable the
b870: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 63  .**          [sc
b880: 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c  ratch memory all
b890: 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ocator]..**.** {
b8a0: 48 31 34 31 35 36 7d 20 41 20 73 75 63 63 65 73  H14156} A succes
b8b0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  sful call to.** 
b8c0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
b8d0: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
b8e0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
b8f0: 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20  HE],S,Z,N).**   
b900: 20 20 20 20 20 20 20 77 68 65 72 65 20 5a 20 61         where Z a
b910: 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65 67  nd N are non-neg
b920: 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 20 61  ative integers a
b930: 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nd .**          
b940: 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  S is a pointer t
b950: 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d 65 6d  o an aligned mem
b960: 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 20 6c  ory buffer not l
b970: 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20  ess than.**     
b980: 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73 20 69       Z*N bytes i
b990: 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63 61 75  n size shall cau
b9a0: 73 65 20 53 20 74 6f 20 62 65 20 75 73 65 64 20  se S to be used 
b9b0: 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  by the.**       
b9c0: 20 20 20 5b 70 61 67 65 63 61 63 68 65 20 6d 65     [pagecache me
b9d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
b9e0: 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73 20 4e  for as many as N
b9f0: 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73 0a 2a   simulataneous.*
ba00: 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63  *          alloc
ba10: 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66 20 73  ations each of s
ba20: 69 7a 65 20 5a 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ize Z..**.** {H1
ba30: 34 31 35 39 7d 20 41 20 73 75 63 63 65 73 73 66  4159} A successf
ba40: 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20  ul call to.**   
ba50: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
ba60: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
ba70: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
ba80: 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20  ],S,Z,N).**     
ba90: 20 20 20 20 20 77 68 65 72 65 20 53 20 69 73 20       where S is 
baa0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  a NULL pointer s
bab0: 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65  hall disable the
bac0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 61  .**          [pa
bad0: 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  gecache memory a
bae0: 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a  llocator]..**.**
baf0: 20 7b 48 31 34 31 36 32 7d 20 41 20 73 75 63 63   {H14162} A succ
bb00: 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
bb10: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
bb20: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
bb30: 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20  EAP],H,Z,N).**  
bb40: 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a 20          where Z 
bb50: 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65  and N are non-ne
bb60: 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 20  gative integers 
bb70: 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  and .**         
bb80: 20 48 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20   H is a pointer 
bb90: 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d 65  to an aligned me
bba0: 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 20  mory buffer not 
bbb0: 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20  less than.**    
bbc0: 20 20 20 20 20 20 5a 20 62 79 74 65 73 20 69 6e        Z bytes in
bbd0: 20 73 69 7a 65 20 73 68 61 6c 6c 20 65 6e 61 62   size shall enab
bbe0: 6c 65 20 74 68 65 20 5b 6d 65 6d 73 79 73 35 5d  le the [memsys5]
bbf0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
bc00: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e  r.**          an
bc10: 64 20 63 61 75 73 65 20 69 74 20 74 6f 20 75 73  d cause it to us
bc20: 65 20 62 75 66 66 65 72 20 53 20 61 73 20 69 74  e buffer S as it
bc30: 73 20 6d 65 6d 6f 72 79 20 73 6f 75 72 63 65 20  s memory source 
bc40: 61 6e 64 20 74 6f 20 75 73 65 0a 2a 2a 20 20 20  and to use.**   
bc50: 20 20 20 20 20 20 20 61 20 6d 69 6e 69 6d 75 6d         a minimum
bc60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
bc70: 20 6f 66 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   of N..**.** {H1
bc80: 34 31 36 35 7d 20 41 20 73 75 63 63 65 73 73 66  4165} A successf
bc90: 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
bca0: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
bcb0: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
bcc0: 2c 48 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20  ,H,Z,N).**      
bcd0: 20 20 20 20 77 68 65 72 65 20 48 20 69 73 20 61      where H is a
bce0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73 68   NULL pointer sh
bcf0: 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65 0a  all disable the.
bd00: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 6d 65 6d  **          [mem
bd10: 73 79 73 35 5d 20 6d 65 6d 6f 72 79 20 61 6c 6c  sys5] memory all
bd20: 6f 63 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ocator..**.** {H
bd30: 31 34 31 36 38 7d 20 41 20 73 75 63 63 65 73 73  14168} A success
bd40: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
bd50: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
bd60: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
bd70: 41 53 49 44 45 5d 2c 5a 2c 4e 29 0a 2a 2a 20 20  ASIDE],Z,N).**  
bd80: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 63 61          shall ca
bd90: 75 73 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  use the default 
bda0: 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
bdb0: 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
bdc0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 20 20  figuration.**   
bdd0: 20 20 20 20 20 20 20 66 6f 72 20 6e 65 77 20 5b         for new [
bde0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
bdf0: 69 6f 6e 73 5d 20 74 6f 20 62 65 20 4e 20 73 6c  ions] to be N sl
be00: 6f 74 73 20 6f 66 20 5a 20 62 79 74 65 73 20 65  ots of Z bytes e
be10: 61 63 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ach..*/.SQLITE_E
be20: 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20  XPERIMENTAL int 
be30: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
be40: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
be50: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
be60: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
be70: 6e 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 34 32  nnections  {H142
be80: 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20  00} <S20000>.** 
be90: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
bea0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
beb0: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
bec0: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
bed0: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
bee0: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
bef0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
bf00: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
bf10: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
bf20: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
bf30: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
bf40: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
bf50: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
bf60: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
bf70: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
bf80: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
bf90: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
bfa0: 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  ).  The.** sqlit
bfb0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
bfc0: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c  nterface can onl
bfd0: 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69  y be used immedi
bfe0: 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74  ately after.** t
bff0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
c000: 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  ection is create
c010: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c020: 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _open()],.** [sq
c030: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
c040: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
c050: 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a  n_v2()].  .**.**
c060: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
c070: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c080: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
c090: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  .)  is the.** co
c0a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
c0b0: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
c0c0: 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  de that indicate
c0d0: 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74  s what.** aspect
c0e0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
c0f0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
c100: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
c110: 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63  d..** The only c
c120: 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76  hoice for this v
c130: 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  alue is [SQLITE_
c140: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
c150: 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62  DE]..** New verb
c160: 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
c170: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
c180: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
c190: 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69  QLite..** Additi
c1a0: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64  onal arguments d
c1b0: 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72  epend on the ver
c1c0: 62 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  b..**.** INVARIA
c1d0: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32  NTS:.**.** {H142
c1e0: 30 33 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  03} A call to [s
c1f0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c200: 28 44 2c 56 2c 2e 2e 2e 29 5d 20 73 68 61 6c 6c  (D,V,...)] shall
c210: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
c220: 4f 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  OK].**          
c230: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
c240: 68 65 20 63 61 6c 6c 20 69 73 20 73 75 63 63 65  he call is succe
c250: 73 73 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ssful..**.** {H1
c260: 34 32 30 36 7d 20 49 66 20 6f 6e 65 20 6f 72 20  4206} If one or 
c270: 6d 6f 72 65 20 73 6c 6f 74 73 20 6f 66 20 74 68  more slots of th
c280: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  e [lookaside mem
c290: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66  ory allocator] f
c2a0: 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
c2b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c2c0: 69 6f 6e 5d 20 44 20 61 72 65 20 69 6e 20 75 73  ion] D are in us
c2d0: 65 2c 20 74 68 65 6e 20 61 20 63 61 6c 6c 20 74  e, then a call t
c2e0: 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
c2f0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c300: 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f  ](D,[SQLITE_DBCO
c310: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
c320: 2e 2e 2e 29 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  ...) shall.**   
c330: 20 20 20 20 20 20 20 66 61 69 6c 20 77 69 74 68         fail with
c340: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59   an [SQLITE_BUSY
c350: 5d 20 72 65 74 75 72 6e 20 63 6f 64 65 2e 0a 2a  ] return code..*
c360: 2a 0a 2a 2a 20 7b 48 31 34 32 30 39 7d 20 41 20  *.** {H14209} A 
c370: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
c380: 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  to .**          
c390: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
c3a0: 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42  ig](D,[SQLITE_DB
c3b0: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
c3c0: 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a  ],B,Z,N) where.*
c3d0: 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73 20  *          D is 
c3e0: 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  an open [databas
c3f0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
c400: 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 70 6f  d Z and N are po
c410: 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  sitive.**       
c420: 20 20 20 69 6e 74 65 67 65 72 73 20 61 6e 64 20     integers and 
c430: 42 20 69 73 20 61 6e 20 61 6c 69 67 6e 65 64 20  B is an aligned 
c440: 62 75 66 66 65 72 20 61 74 20 6c 65 61 73 74 20  buffer at least 
c450: 5a 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  Z*N bytes in siz
c460: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  e.**          sh
c470: 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 5b 6c  all cause the [l
c480: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
c490: 61 6c 6c 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44  allocator] for D
c4a0: 20 74 6f 20 75 73 65 20 62 75 66 66 65 72 20 42   to use buffer B
c4b0: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69   .**          wi
c4c0: 74 68 20 4e 20 73 6c 6f 74 73 20 6f 66 20 5a 20  th N slots of Z 
c4d0: 62 79 74 65 73 20 65 61 63 68 2e 0a 2a 2a 0a 2a  bytes each..**.*
c4e0: 2a 20 7b 48 31 34 32 31 32 7d 20 41 20 73 75 63  * {H14212} A suc
c4f0: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
c500: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
c510: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 5d  lite3_db_config]
c520: 28 44 2c 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  (D,[SQLITE_DBCON
c530: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42  FIG_LOOKASIDE],B
c540: 2c 5a 2c 4e 29 20 77 68 65 72 65 0a 2a 2a 20 20  ,Z,N) where.**  
c550: 20 20 20 20 20 20 20 20 44 20 69 73 20 61 6e 20          D is an 
c560: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
c570: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5a  onnection] and Z
c580: 20 61 6e 64 20 4e 20 61 72 65 20 70 6f 73 69 74   and N are posit
c590: 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
c5a0: 69 6e 74 65 67 65 72 73 20 61 6e 64 20 42 20 69  integers and B i
c5b0: 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73  s NULL pointer s
c5c0: 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 0a 2a  hall cause the.*
c5d0: 2a 20 20 20 20 20 20 20 20 20 20 5b 6c 6f 6f 6b  *          [look
c5e0: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
c5f0: 6f 63 61 74 6f 72 5d 20 66 6f 72 20 44 20 74 6f  ocator] for D to
c600: 20 61 20 6f 62 74 61 69 6e 20 5a 2a 4e 20 62 79   a obtain Z*N by
c610: 74 65 20 62 75 66 66 65 72 0a 2a 2a 20 20 20 20  te buffer.**    
c620: 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 70        from the p
c630: 72 69 6d 61 72 79 20 6d 65 6d 6f 72 79 20 61 6c  rimary memory al
c640: 6c 6f 63 61 74 6f 72 20 61 6e 64 20 75 73 65 20  locator and use 
c650: 74 68 61 74 20 62 75 66 66 65 72 0a 2a 2a 20 20  that buffer.**  
c660: 20 20 20 20 20 20 20 20 77 69 74 68 20 4e 20 6c          with N l
c670: 6f 6f 6b 61 73 69 64 65 20 73 6c 6f 74 73 20 6f  ookaside slots o
c680: 66 20 5a 20 62 79 74 65 73 20 65 61 63 68 2e 0a  f Z bytes each..
c690: 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31 35 7d 20 41  **.** {H14215} A
c6a0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
c6b0: 20 74 6f 20 0a 2a 2a 20 20 20 20 20 20 20 20 20   to .**         
c6c0: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
c6d0: 66 69 67 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 44  fig](D,[SQLITE_D
c6e0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
c6f0: 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68 65 72 65 0a  E],B,Z,N) where.
c700: 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 69 73  **          D is
c710: 20 61 6e 20 6f 70 65 6e 20 5b 64 61 74 61 62 61   an open [databa
c720: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
c730: 6e 64 20 5a 20 61 6e 64 20 4e 20 61 72 65 20 7a  nd Z and N are z
c740: 65 72 6f 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20  ero shall.**    
c750: 20 20 20 20 20 20 64 69 73 61 62 6c 65 20 74 68        disable th
c760: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  e [lookaside mem
c770: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 66  ory allocator] f
c780: 6f 72 20 44 2e 0a 2a 2a 0a 2a 2a 0a 2a 2f 0a 53  or D..**.**.*/.S
c790: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
c7a0: 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  AL int sqlite3_d
c7b0: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
c7c0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
c7d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c7e0: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
c7f0: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31  ion Routines {H1
c800: 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a  0155} <S20120>.*
c810: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
c820: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
c830: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
c840: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
c850: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
c860: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
c870: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
c880: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
c890: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
c8a0: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
c8b0: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
c8c0: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
c8d0: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
c8e0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
c8f0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
c900: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
c910: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
c920: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
c930: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
c940: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
c950: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
c960: 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74  LLOC].  By creat
c970: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
c980: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
c990: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
c9a0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
c9b0: 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f  fig()] during co
c9c0: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a  nfiguration, an.
c9d0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  ** application c
c9e0: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
c9f0: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
ca00: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
ca10: 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c  ystem.** for SQL
ca20: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
ca30: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
ca40: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
ca50: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
ca60: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
ca70: 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  h a built-in mem
ca80: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
ca90: 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74  at is.** perfect
caa0: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
cab0: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
cac0: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
cad0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
cae0: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
caf0: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
cb00: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
cb10: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
cb20: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
cb30: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
cb40: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
cb50: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
cb60: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
cb70: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
cb80: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
cb90: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
cba0: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
cbb0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
cbc0: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
cbd0: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
cbe0: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
cbf0: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
cc00: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
cc10: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
cc20: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
cc30: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
cc40: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
cc50: 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64  lloc, xFree, and
cc60: 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64   xRealloc method
cc70: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
cc80: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
cc90: 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65  , free(), and re
cca0: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e  alloc() function
ccb0: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
ccc0: 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ard library..**.
ccd0: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
cce0: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
ccf0: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
cd00: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
cd10: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
cd20: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
cd30: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
cd40: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
cd50: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
cd60: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
cd70: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
cd80: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
cd90: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
cda0: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
cdb0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
cdc0: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
cdd0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
cde0: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
cdf0: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
ce00: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
ce10: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
ce20: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
ce30: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
ce40: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ce50: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
ce60: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
ce70: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
ce80: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
ce90: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
cea0: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
ceb0: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a   power of 2..**.
cec0: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
ced0: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
cee0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
cef0: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
cf00: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
cf10: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
cf20: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
cf30: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
cf40: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
cf50: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
cf60: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
cf70: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
cf80: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
cf90: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
cfa0: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
cfb0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
cfc0: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
cfd0: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
cfe0: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
cff0: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
d000: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
d010: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
d020: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79  xShutdown..*/.ty
d030: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
d040: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d050: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
d060: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
d070: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d080: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
d090: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
d0a0: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
d0b0: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
d0c0: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
d0d0: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
d0e0: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
d0f0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
d100: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
d110: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
d120: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
d130: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
d140: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
d150: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
d160: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
d170: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
d180: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
d190: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
d1a0: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
d1b0: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
d1c0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
d1d0: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
d1e0: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
d1f0: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
d200: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
d210: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
d220: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
d230: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
d240: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
d250: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
d260: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
d270: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
d280: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
d290: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
d2a0: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
d2b0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
d2c0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
d2d0: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31  tion Options {H1
d2e0: 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0160} <S20000>.*
d2f0: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
d300: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
d310: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
d320: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
d330: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d340: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
d350: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
d360: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
d370: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
d380: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
d390: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
d3a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d3b0: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
d3c0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
d3d0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
d3e0: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
d3f0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d400: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
d410: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
d420: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
d430: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
d440: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
d450: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d460: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
d470: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
d480: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
d490: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
d4a0: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
d4b0: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
d4c0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
d4d0: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
d4e0: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
d4f0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d500: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
d510: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
d520: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d530: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
d540: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
d550: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
d560: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
d570: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e  on.  This option
d580: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
d590: 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
d5a0: 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
d5b0: 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
d5c0: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
d5d0: 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
d5e0: 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  hread.</dd>.**.*
d5f0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d600: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
d610: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
d620: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
d630: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
d640: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
d650: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
d660: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
d670: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
d680: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
d690: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
d6a0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
d6b0: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
d6c0: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
d6d0: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
d6e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d6f0: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
d700: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
d710: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
d720: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
d730: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
d740: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
d750: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
d760: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
d770: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
d780: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
d790: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
d7a0: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
d7b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d7c0: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
d7d0: 74 69 6d 65 2e 20 20 53 65 65 20 74 68 65 20 5b  time.  See the [
d7e0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 0a  threading mode].
d7f0: 2a 2a 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  ** documentation
d800: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
d810: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c 2f 64 64  information.</dd
d820: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d830: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
d840: 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
d850: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
d860: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
d870: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
d880: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
d890: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
d8a0: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
d8b0: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
d8c0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
d8d0: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
d8e0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
d8f0: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
d900: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
d910: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
d920: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
d930: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d940: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
d950: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
d960: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
d970: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
d980: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
d990: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d9a0: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
d9b0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
d9c0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
d9d0: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
d9e0: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
d9f0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
da00: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
da10: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
da20: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
da30: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
da40: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
da50: 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  ..** See the [th
da60: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
da70: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
da80: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
da90: 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  mation.</dd>.**.
daa0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
dab0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
dac0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
dad0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
dae0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
daf0: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
db00: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
db10: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
db20: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
db30: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
db40: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
db50: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
db60: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
db70: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
db80: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
db90: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
dba0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
dbb0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
dbc0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
dbd0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
dbe0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
dbf0: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
dc00: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
dc10: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
dc20: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
dc30: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
dc40: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
dc50: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
dc60: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
dc70: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
dc80: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
dc90: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
dca0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
dcb0: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
dcc0: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
dcd0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
dce0: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
dcf0: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
dd00: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
dd10: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
dd20: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
dd30: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
dd40: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
dd50: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
dd60: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
dd70: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
dd80: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
dd90: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
dda0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
ddb0: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
ddc0: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
ddd0: 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
dde0: 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
ddf0: 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
de00: 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
de10: 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
de20: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
de30: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
de40: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
de50: 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 57  ** statistics. W
de60: 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74 68  hen disabled, th
de70: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
de80: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
de90: 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65  come .** non-ope
dea0: 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
deb0: 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
dec0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
ded0: 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
dee0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
def0: 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
df00: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
df10: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
df20: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
df30: 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
df40: 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f  **   </ul>.** </
df50: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
df60: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
df70: 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
df80: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
df90: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
dfa0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
dfb0: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
dfc0: 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
dfd0: 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
dfe0: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
dff0: 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 74  ts:  A pointer t
e000: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68  o the memory, th
e010: 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
e020: 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  h scratch buffer
e030: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
e040: 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72 73  umber of buffers
e050: 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a   (N).  The sz.**
e060: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
e070: 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  e a multiple of 
e080: 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61 6d  16. The sz param
e090: 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61  eter should be a
e0a0: 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c 61   few bytes.** la
e0b0: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61 63  rger than the ac
e0c0: 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70 61  tual scratch spa
e0d0: 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65 20  ce required due 
e0e0: 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61  internal overhea
e0f0: 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 0a  d..** The first.
e100: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
e110: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
e120: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
e130: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
e140: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   of memory..** S
e150: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
e160: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  o more than one 
e170: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 61  scratch buffer a
e180: 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61  t once per threa
e190: 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  d, so.** N shoul
e1a0: 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20  d be set to the 
e1b0: 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
e1c0: 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
e1d0: 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70  ds.  The sz.** p
e1e0: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
e1f0: 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20 73  be 6 times the s
e200: 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
e210: 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
e220: 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63   size..** Scratc
e230: 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75 73  h buffers are us
e240: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
e250: 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20  e btree balance 
e260: 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a  operation.  If.*
e270: 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c 61  * The btree bala
e280: 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69 74  ncer needs addit
e290: 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79  ional memory bey
e2a0: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
e2b0: 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74  ided by.** scrat
e2c0: 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69 66  ch buffers or if
e2d0: 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66 66   no scratch buff
e2e0: 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65 63  er space is spec
e2f0: 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69  ified, then SQLi
e300: 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73  te.** goes to [s
e310: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
e320: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
e330: 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c  emory it needs.<
e340: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e350: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
e360: 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
e370: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
e380: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
e390: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
e3a0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
e3b0: 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64  use for.** the d
e3c0: 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
e3d0: 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
e3e0: 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ult page cache i
e3f0: 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a  mplemenation.  .
e400: 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
e410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
e420: 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
e430: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
e440: 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
e450: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
e460: 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
e470: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
e480: 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a  _PCACHE option..
e490: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
e4a0: 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
e4b0: 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70  this option: A p
e4c0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
e4d0: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
e4e0: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
e4f0: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
e500: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
e510: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
e520: 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  sz argument must
e530: 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74   be a power of t
e540: 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
e550: 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 20 66  nd 32768.  The f
e560: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
e570: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
e580: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
e590: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
e5a0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
e5b0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
e5c0: 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
e5d0: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
e5e0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
e5f0: 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
e600: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
e610: 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
e620: 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
e630: 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 64  to cache.  If ad
e640: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
e650: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
e660: 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
e670: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
e680: 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
e690: 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
e6a0: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
e6b0: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
e6c0: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
e6d0: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
e6e0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
e6f0: 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20  n might use one 
e700: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e  or more of the N
e710: 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64   buffers to hold
e720: 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f   .** memory acco
e730: 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69  unting informati
e740: 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  on. </dd>.**.** 
e750: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
e760: 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
e770: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
e780: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
e790: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
e7a0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
e7b0: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
e7c0: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
e7d0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e7e0: 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
e7f0: 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
e800: 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
e810: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
e820: 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
e830: 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
e840: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
e850: 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f   arguments: A po
e860: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
e870: 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ory, the number 
e880: 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
e890: 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
e8a0: 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
e8b0: 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
e8c0: 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66 69  e.  If.** the fi
e8d0: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
e8e0: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
e8f0: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
e900: 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
e910: 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
e920: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
e930: 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
e940: 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
e950: 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
e960: 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
e970: 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
e980: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
e990: 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a  ALLOC].  If the.
e9a0: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
e9b0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
e9c0: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
e9d0: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
e9e0: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
e9f0: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
ea00: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
ea10: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
ea20: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
ea30: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
ea40: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
ea50: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
ea60: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
ea70: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ea80: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
ea90: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
eaa0: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
eab0: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
eac0: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
ead0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
eae0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
eaf0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
eb00: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
eb10: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
eb20: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
eb30: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
eb40: 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
eb50: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
eb60: 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
eb70: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
eb80: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
eb90: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
eba0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
ebb0: 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
ebc0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
ebd0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
ebe0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
ebf0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
ec00: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
ec10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
ec20: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
ec30: 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
ec40: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
ec50: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
ec60: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
ec70: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
ec80: 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
ec90: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20  utines..** This 
eca0: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
ecb0: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
ecc0: 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
ecd0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
ece0: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
ecf0: 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
ed00: 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
ed10: 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
ed20: 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
ed30: 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
ed40: 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ample.</dd>.**.*
ed50: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
ed60: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
ed70: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
ed80: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
ed90: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
eda0: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66  etermine the def
edb0: 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  ault.** memory a
edc0: 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69  llcation lookasi
edd0: 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e  de optimization.
ede0: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
edf0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
ee00: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
ee10: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
ee20: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
ee30: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
ee40: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
ee50: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
ee60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ee70: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ee80: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
ee90: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
eea0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
eeb0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
eec0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
eed0: 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61   pointer to.** a
eee0: 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
eef0: 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
ef00: 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
ef10: 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
ef20: 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
ef30: 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
ef40: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
ef50: 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  .  SQLite makes 
ef60: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
ef70: 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73   object and uses
ef80: 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63   it for page cac
ef90: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
efa0: 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  tions.</dd>.**.*
efb0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
efc0: 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64  FIG_GETPCACHE</d
efd0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
efe0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
eff0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
f000: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
f010: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
f020: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
f030: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  s] object.  SQLi
f040: 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65  te copies of the
f050: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65   current.** page
f060: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
f070: 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
f080: 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
f090: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
f0a0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
f0b0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
f0c0: 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
f0d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
f0e0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
f0f0: 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
f100: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f110: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
f120: 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
f130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f140: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
f150: 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
f160: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
f170: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f180: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
f190: 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
f1a0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
f1b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f1c0: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
f1d0: 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
f1e0: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
f1f0: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
f200: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
f210: 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
f220: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
f230: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
f240: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
f250: 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
f260: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
f270: 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
f280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f290: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
f2a0: 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
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 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
f2d0: 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
f2e0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
f2f0: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
f300: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
f310: 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
f320: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
f330: 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
f340: 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
f350: 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
f360: 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
f370: 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#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 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
f3a0: 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
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 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
f3d0: 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c        14  /* sql
f3e0: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
f3f0: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
f400: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
f410: 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f  TPCACHE    15  /
f420: 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
f430: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a  _methods* */../*
f440: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
f450: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
f460: 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c 53 32  ons {H10170} <S2
f470: 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0000>.** EXPERIM
f480: 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ENTAL.**.** Thes
f490: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
f4a0: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
f4b0: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
f4c0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
f4d0: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
f4e0: 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
f4f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
f500: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
f510: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
f520: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
f530: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
f540: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
f550: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
f560: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
f570: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
f580: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
f590: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
f5a0: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
f5b0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
f5c0: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
f5d0: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
f5e0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
f5f0: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
f600: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
f610: 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
f620: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
f630: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
f640: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
f650: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
f660: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
f670: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
f680: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f690: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
f6a0: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
f6b0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
f6c0: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
f6d0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
f6e0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
f6f0: 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
f700: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
f710: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
f720: 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
f730: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
f740: 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
f750: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
f760: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
f770: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f780: 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
f790: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
f7a0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
f7b0: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
f7c0: 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
f7d0: 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
f7e0: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20 20  kaside memory.  
f7f0: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
f800: 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55 4c  ument may be NUL
f810: 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
f820: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
f830: 63 61 74 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  cate the lookasi
f840: 64 65 0a 2a 2a 20 62 75 66 66 65 72 20 69 74 73  de.** buffer its
f850: 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
f860: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54  e3_malloc()].  T
f870: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
f880: 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
f890: 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
f8a0: 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
f8b0: 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 61 72  and the third ar
f8c0: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
f8d0: 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
f8e0: 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
f8f0: 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
f900: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
f910: 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
f920: 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
f930: 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
f940: 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
f950: 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
f960: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  s.</dd>.**.** </
f970: 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
f980: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
f990: 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31  OOKASIDE    1001
f9a0: 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
f9b0: 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt */.../*.** CA
f9c0: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
f9d0: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
f9e0: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
f9f0: 7b 48 31 32 32 30 30 7d 20 3c 53 31 30 37 30 30  {H12200} <S10700
fa00: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
fa10: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
fa20: 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
fa30: 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
fa40: 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
fa50: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
fa60: 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
fa70: 66 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78  f SQLite. The ex
fa80: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
fa90: 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
faa0: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
fab0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
fac0: 6d 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73  mpatibility cons
fad0: 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  iderations..**.*
fae0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
faf0: 0a 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45 61 63  .** {H12201} Eac
fb00: 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20  h new [database 
fb10: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c  connection] shal
fb20: 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20 20  l have the.**   
fb30: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
fb40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
fb50: 65 61 74 75 72 65 20 64 69 73 61 62 6c 65 64 20  eature disabled 
fb60: 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
fb70: 2a 20 7b 48 31 32 32 30 32 7d 20 54 68 65 20 5b  * {H12202} The [
fb80: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
fb90: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44 2c  _result_codes(D,
fba0: 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  F)] interface sh
fbb0: 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20  all enable.**   
fbc0: 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64         [extended
fbd0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
fbe0: 6f 72 20 74 68 65 20 20 5b 64 61 74 61 62 61 73  or the  [databas
fbf0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
fc00: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74  **          if t
fc10: 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 20 69  he F parameter i
fc20: 73 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62  s true, or disab
fc30: 6c 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20  le them if F is 
fc40: 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  false..*/.int sq
fc50: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
fc60: 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
fc70: 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
fc80: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fc90: 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
fca0: 6f 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c 53  owid {H12220} <S
fcb0: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63  10700>.**.** Eac
fcc0: 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
fcd0: 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
fce0: 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
fcf0: 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
fd00: 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
fd10: 22 72 6f 77 69 64 22 2e 20 54 68 65 20 72 6f 77  "rowid". The row
fd20: 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
fd30: 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
fd40: 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
fd50: 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
fd60: 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
fd70: 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
fd80: 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
fd90: 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
fda0: 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
fdb0: 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a  d columns. If.**
fdc0: 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
fdd0: 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
fde0: 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
fdf0: 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f  KEY then that co
fe00: 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68  lumn.** is anoth
fe10: 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65  er alias for the
fe20: 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68   rowid..**.** Th
fe30: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
fe40: 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  ns the rowid of 
fe50: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
fe60: 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
fe70: 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20  NSERT] into the 
fe80: 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
fe90: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
fea0: 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
feb0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
fec0: 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73  .  If no success
fed0: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
fee0: 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
fef0: 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
ff00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
ff10: 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
ff20: 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 5b  d..**.** If an [
ff30: 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
ff40: 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
ff50: 20 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20   then the rowid 
ff60: 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
ff70: 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e  ** row is return
ff80: 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
ff90: 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ne as long as th
ffa0: 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e  e trigger is run
ffb0: 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
ffc0: 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65  e the trigger te
ffd0: 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61  rminates, the va
ffe0: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
fff0: 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
10000 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c  reverts to the l
10010 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74  ast value insert
10020 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  ed before the tr
10030 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a  igger fired..**.
10040 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  ** An [INSERT] t
10050 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
10060 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
10070 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
10080 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
10090 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
100a0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
100b0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
100c0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
100d0 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54 20  e.  Thus INSERT 
100e0 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
100f0 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
10100 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
10110 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
10120 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
10130 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
10140 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
10150 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
10160 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
10170 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20 49  n fails.  When I
10180 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
10190 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
101a0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
101b0 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
101c0 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
101d0 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
101e0 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
101f0 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
10200 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
10210 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
10220 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
10230 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
10240 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
10250 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
10260 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
10270 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 46  terface..**.** F
10280 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
10290 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
102a0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
102b0 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
102c0 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
102d0 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
102e0 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
102f0 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   back..**.** INV
10300 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
10310 48 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c  H12221} The [sql
10320 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
10330 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69  _rowid()] functi
10340 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  on shall return 
10350 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 20 20 20  the rowid.**    
10360 20 20 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73        of the mos
10370 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
10380 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 70 65 72  ful [INSERT] per
10390 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61  formed on the sa
103a0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  me.**          [
103b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
103c0 69 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20  ion] and within 
103d0 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68  the same or high
103e0 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20  er level.**     
103f0 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e       trigger con
10400 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66  text, or zero if
10410 20 74 68 65 72 65 20 68 61 76 65 20 62 65 65 6e   there have been
10420 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 0a 2a   no qualifying.*
10430 2a 20 20 20 20 20 20 20 20 20 20 5b 49 4e 53 45  *          [INSE
10440 52 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  RT] statements..
10450 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20 54  **.** {H12223} T
10460 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
10470 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
10480 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
10490 72 65 74 75 72 6e 20 74 68 65 0a 2a 2a 20 20 20  return the.**   
104a0 20 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75         same valu
104b0 65 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  e when called fr
104c0 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  om the same trig
104d0 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20  ger context.**  
104e0 20 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74          immediat
104f0 65 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61  ely before and a
10500 66 74 65 72 20 61 20 5b 52 4f 4c 4c 42 41 43 4b  fter a [ROLLBACK
10510 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  ]..**.** ASSUMPT
10520 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
10530 32 33 32 7d 20 49 66 20 61 20 73 65 70 61 72 61  232} If a separa
10540 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
10550 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
10560 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
10570 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61            databa
10580 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
10590 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
105a0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
105b0 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  id()].**        
105c0 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75    function is ru
105d0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
105e0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
105f0 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a  insert rowid,.**
10600 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
10610 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
10620 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
10630 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
10640 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  )] is.**        
10650 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20    unpredictable 
10660 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
10670 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
10680 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
10690 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20 69            last i
106a0 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a  nsert rowid..*/.
106b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
106c0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
106d0 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
106e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
106f0 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
10700 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
10710 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c  ified {H12240} <
10720 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10600>.**.** Th
10730 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
10740 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
10750 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
10760 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
10770 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
10780 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
10790 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
107a0 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
107b0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
107c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
107d0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
107e0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
107f0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e  parameter..** On
10800 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ly changes that 
10810 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
10820 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49  cified by the [I
10830 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
10840 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ,.** or [DELETE]
10850 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
10860 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
10870 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
10880 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
10890 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
108a0 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74  . Use the [sqlit
108b0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
108c0 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ()] function.** 
108d0 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
108e0 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
108f0 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  ges including ch
10900 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
10910 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  triggers..**.** 
10920 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
10930 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
10940 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
10950 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
10960 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
10970 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
10980 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
10990 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
109a0 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
109b0 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 52  ide effects of R
109c0 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
109d0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a  t resolution,.**
109e0 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54   rollback, ABORT
109f0 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44 52 4f   processing, DRO
10a00 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79 20 61  P TABLE, or by a
10a10 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68  ny other.** mech
10a20 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f  anisms do not co
10a30 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f  unt as direct ro
10a40 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a  w changes..**.**
10a50 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
10a60 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
10a70 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
10a80 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
10a90 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
10aa0 72 69 70 74 20 6f 66 20 61 20 74 72 69 67 67 65  ript of a trigge
10ab0 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  r.  Most SQL sta
10ac0 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
10ad0 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
10ae0 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
10af0 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
10b00 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
10b10 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
10b20 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
10b30 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
10b40 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
10b50 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
10b60 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
10b70 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
10b80 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
10b90 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
10ba0 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
10bb0 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
10bc0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  ation..**.** Cal
10bd0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
10be0 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
10bf0 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
10c00 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
10c10 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
10c20 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
10c30 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
10c40 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
10c50 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
10c60 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
10c70 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
10c80 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
10c90 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
10ca0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
10cb0 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
10cc0 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
10cd0 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c   Thus, when call
10ce0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
10cf0 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
10d00 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
10d10 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
10d20 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
10d30 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
10d40 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
10d50 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
10d60 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
10d70 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69 74 68  top level.  With
10d80 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61  in the body of a
10d90 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65   trigger,.** the
10da0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
10db0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  () interface can
10dc0 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69   be called to fi
10dd0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
10de0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74  .** changes in t
10df0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
10e00 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
10e10 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
10e20 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  LETE.** statemen
10e30 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64  t within the bod
10e40 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72  y of the same tr
10e50 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65  igger..** Howeve
10e60 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65  r, the number re
10e70 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
10e80 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a  include changes.
10e90 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62  ** caused by sub
10ea0 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74  triggers since t
10eb0 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20  hose have their 
10ec0 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  own context..**.
10ed0 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
10ee0 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64  ents the command
10ef0 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
10f00 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57  ble" without a W
10f10 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62  HERE clause.** b
10f20 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72  y dropping and r
10f30 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61  ecreating the ta
10f40 62 6c 65 2e 20 20 44 6f 69 6e 67 20 73 6f 20 69  ble.  Doing so i
10f50 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68  s much faster th
10f60 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f  an going.** thro
10f70 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67  ugh and deleting
10f80 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d   individual elem
10f90 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61  ents from the ta
10fa0 62 6c 65 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ble.  Because of
10fb0 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a   this.** optimiz
10fc0 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74  ation, the delet
10fd0 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20  ions in "DELETE 
10fe0 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20  FROM table" are 
10ff0 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  not row changes 
11000 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  and.** will not 
11010 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68  be counted by th
11020 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
11030 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  s() or [sqlite3_
11040 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
11050 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72  .** functions, r
11060 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
11070 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
11080 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
11090 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74  iginally.** in t
110a0 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65  he table.  To ge
110b0 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
110c0 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
110d0 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65  r of rows delete
110e0 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54  d, use.** "DELET
110f0 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45  E FROM table WHE
11100 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 20 20  RE 1" instead.  
11110 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 73 69  Or recompile usi
11120 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
11130 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f  E_OMIT_TRUNCATE_
11140 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f  OPTIMIZATION] co
11150 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11160 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65  n to disable the
11170 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  .** optimization
11180 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 73 2e   on all queries.
11190 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
111a0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 31  S:.**.** {H12241
111b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
111c0 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
111d0 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  on shall return 
111e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
111f0 20 20 20 20 20 20 20 20 20 20 72 6f 77 20 63 68            row ch
11200 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
11210 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
11220 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a  INSERT, UPDATE,.
11230 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 44  **          or D
11240 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
11250 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
11260 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
11270 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
11280 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
11290 6f 72 20 68 69 67 68 65 72 20 74 72 69 67 67 65  or higher trigge
112a0 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65  r context, or ze
112b0 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65  ro if there have
112c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74  .**          not
112d0 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 66   been any qualif
112e0 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 73  ying row changes
112f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 33 7d  ..**.** {H12243}
11300 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74   Statements of t
11310 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20  he form "DELETE 
11320 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20  FROM tablename" 
11330 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20  with no.**      
11340 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65      WHERE clause
11350 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73 75 62   shall cause sub
11360 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
11370 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
11380 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
11390 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f 2c   to return zero,
113a0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
113b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
113c0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6f 72  umber of rows or
113d0 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 20  iginally in the 
113e0 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53 53  table..**.** ASS
113f0 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
11400 7b 41 31 32 32 35 32 7d 20 49 66 20 61 20 73 65  {A12252} If a se
11410 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
11420 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
11430 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
11440 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
11450 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73          while [s
11460 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
11470 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
11480 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
11490 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
114a0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
114b0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
114c0 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
114d0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
114e0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
114f0 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
11500 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
11510 64 69 66 69 65 64 20 7b 48 31 32 32 36 30 7d 20  dified {H12260} 
11520 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10600>.**.** T
11530 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
11540 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
11550 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63  of row changes c
11560 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c  aused by INSERT,
11570 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20 44 45  .** UPDATE or DE
11580 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20  LETE statements 
11590 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62  since the [datab
115a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
115b0 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54  was opened..** T
115c0 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65  he count include
115d0 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72  s all changes fr
115e0 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 20 63  om all trigger c
115f0 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65 76 65  ontexts.  Howeve
11600 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20  r,.** the count 
11610 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
11620 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f   changes used to
11630 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41   implement REPLA
11640 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a  CE constraints,.
11650 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20  ** do rollbacks 
11660 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  or ABORT process
11670 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74 61 62  ing, or DROP tab
11680 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a  le processing..*
11690 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20 61 72  * The changes ar
116a0 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f  e counted as soo
116b0 6e 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  n as the stateme
116c0 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
116d0 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  em is.** complet
116e0 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ed (when the sta
116f0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73  tement handle is
11700 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
11710 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
11720 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
11730 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20  lize()])..**.** 
11740 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
11750 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44  s the command "D
11760 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
11770 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45 52  " without a WHER
11780 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64  E clause.** by d
11790 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72  ropping and recr
117a0 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65  eating the table
117b0 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63 68  .  (This is much
117c0 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69   faster than goi
117d0 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e  ng.** through an
117e0 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76  d deleting indiv
117f0 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66  idual elements f
11800 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20  rom the table.) 
11810 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73   Because of this
11820 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  .** optimization
11830 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20  , the deletions 
11840 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  in "DELETE FROM 
11850 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72  table" are not r
11860 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a  ow changes and.*
11870 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f  * will not be co
11880 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  unted by the sql
11890 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f  ite3_changes() o
118a0 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  r [sqlite3_total
118b0 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66  _changes()].** f
118c0 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64  unctions, regard
118d0 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62  less of the numb
118e0 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74  er of elements t
118f0 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61  hat were origina
11900 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61  lly.** in the ta
11910 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20  ble.  To get an 
11920 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f  accurate count o
11930 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
11940 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73  rows deleted, us
11950 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f  e.** "DELETE FRO
11960 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22  M table WHERE 1"
11970 20 69 6e 73 74 65 61 64 2e 20 20 20 4f 72 20 72   instead.   Or r
11980 65 63 6f 6d 70 69 6c 65 20 75 73 69 6e 67 20 74  ecompile using t
11990 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d  he.** [SQLITE_OM
119a0 49 54 5f 54 52 55 4e 43 41 54 45 5f 4f 50 54 49  IT_TRUNCATE_OPTI
119b0 4d 49 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70 69 6c  MIZATION] compil
119c0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 6f  e-time option to
119d0 20 64 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20   disable the.** 
119e0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 6f 6e 20  optimization on 
119f0 61 6c 6c 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  all queries..**.
11a00 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
11a10 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
11a20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
11a30 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
11a40 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 31 7d 20  .**.** {H12261} 
11a50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  The [sqlite3_tot
11a60 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65  al_changes()] re
11a70 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20  turns the total 
11a80 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20  number.**       
11a90 20 20 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65     of row change
11aa0 73 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45  s caused by INSE
11ab0 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f  RT, UPDATE, and/
11ac0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20  or DELETE.**    
11ad0 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73        statements
11ae0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
11af0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11b00 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20  n], in any.**   
11b10 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63         trigger c
11b20 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68  ontext, since th
11b30 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
11b40 63 74 69 6f 6e 20 77 61 73 20 63 72 65 61 74 65  ction was create
11b50 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 33  d..**.** {H12263
11b60 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  } Statements of 
11b70 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45  the form "DELETE
11b80 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22   FROM tablename"
11b90 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20   with no.**     
11ba0 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73       WHERE claus
11bb0 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e  e shall not chan
11bc0 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
11bd0 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
11be0 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f    by [sqlite3_to
11bf0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a  tal_changes()]..
11c00 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
11c10 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 36 34  S:.**.** {A12264
11c20 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  } If a separate 
11c30 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
11c40 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
11c50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11c60 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
11c70 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
11c80 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
11c90 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
11ca0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20   the value.**   
11cb0 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20         returned 
11cc0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
11cd0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
11ce0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
11cf0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
11d00 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
11d10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
11d20 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
11d30 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31  unning Query {H1
11d40 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a  2270} <S30500>.*
11d50 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
11d60 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
11d70 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
11d80 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
11d90 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
11da0 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
11db0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
11dc0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
11dd0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
11de0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
11df0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
11e00 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
11e10 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
11e20 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
11e30 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
11e40 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
11e50 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
11e60 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  diately..**.** I
11e70 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
11e80 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
11e90 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
11ea0 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
11eb0 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
11ec0 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
11ed0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
11ee0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
11ef0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
11f00 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
11f10 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
11f20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11f30 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
11f40 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
11f50 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
11f60 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
11f70 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
11f80 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
11f90 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
11fa0 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
11fb0 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
11fc0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
11fd0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
11fe0 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
11ff0 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
12000 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
12010 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
12020 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
12030 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
12040 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  * An SQL operati
12050 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
12060 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
12070 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
12080 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  RUPT]..** If the
12090 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
120a0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
120b0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
120c0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
120d0 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
120e0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
120f0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
12100 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
12110 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
12120 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
12130 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20  ically..**.** A 
12140 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
12150 69 6e 74 65 72 72 75 70 74 28 29 20 68 61 73 20  interrupt() has 
12160 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
12170 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
12180 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
12190 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e  after sqlite3_in
121a0 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
121b0 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
121c0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  NTS:.**.** {H122
121d0 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  71} The [sqlite3
121e0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e  _interrupt()] in
121f0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72  terface will for
12200 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a  ce all running.*
12210 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73  *          SQL s
12220 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
12230 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ated with the sa
12240 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
12250 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
12260 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72     to halt after
12270 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d   processing at m
12280 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e  ost one addition
12290 61 6c 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  al row of data..
122a0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 32 7d 20 41  **.** {H12272} A
122b0 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
122c0 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
122d0 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  pted by [sqlite3
122e0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
122f0 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72            will r
12300 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
12310 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20  TERRUPT]..**.** 
12320 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
12330 2a 2a 20 7b 41 31 32 32 37 39 7d 20 49 66 20 74  ** {A12279} If t
12340 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
12350 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
12360 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
12370 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20  errupt()].**    
12380 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67        is running
12390 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
123a0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
123b0 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  pen..*/.void sql
123c0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
123d0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
123e0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
123f0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
12400 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
12410 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20 3c 53  lete {H10510} <S
12420 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  70200>.**.** The
12430 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
12440 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61  useful for comma
12450 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
12460 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
12470 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
12480 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
12490 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65  s to form comple
124a0 74 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65  te a SQL stateme
124b0 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
124c0 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
124d0 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
124e0 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
124f0 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
12500 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73  r parsing.  Thes
12510 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
12520 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 69 6e  n true if the in
12530 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
12540 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
12550 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
12560 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65  ment.  A stateme
12570 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
12580 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
12590 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
125a0 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
125b0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72   and is not a fr
125c0 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43  agment of a.** C
125d0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
125e0 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f  atement.  Semico
125f0 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
12600 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
12610 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
12620 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
12630 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
12640 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
12650 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
12660 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
12670 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
12680 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
12690 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
126a0 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
126b0 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
126c0 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
126d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
126e0 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
126f0 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
12700 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
12710 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
12720 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
12730 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
12740 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
12750 0a 2a 2a 20 7b 48 31 30 35 31 31 7d 20 41 20 73  .** {H10511} A s
12760 75 63 63 65 73 73 66 75 6c 20 65 76 61 6c 75 61  uccessful evalua
12770 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
12780 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 0a  _complete()] or.
12790 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
127a0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
127b0 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20 73 68 61  )] functions sha
127c0 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ll.**          r
127d0 65 74 75 72 6e 20 61 20 6e 75 6d 65 72 69 63 20  eturn a numeric 
127e0 31 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  1 if and only if
127f0 20 74 68 65 20 6c 61 73 74 20 6e 6f 6e 2d 77 68   the last non-wh
12800 69 74 65 73 70 61 63 65 0a 2a 2a 20 20 20 20 20  itespace.**     
12810 20 20 20 20 20 74 6f 6b 65 6e 20 69 6e 20 74 68       token in th
12820 65 69 72 20 69 6e 70 75 74 20 69 73 20 61 20 73  eir input is a s
12830 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 20 69 73  emicolon that is
12840 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 0a   not in between.
12850 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
12860 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66  BEGIN and END of
12870 20 61 20 43 52 45 41 54 45 20 54 52 49 47 47 45   a CREATE TRIGGE
12880 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  R statement..**.
12890 2a 2a 20 7b 48 31 30 35 31 32 7d 20 49 66 20 61  ** {H10512} If a
128a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
128b0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
128c0 64 75 72 69 6e 67 20 61 6e 20 69 6e 76 6f 63 61  during an invoca
128d0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
128e0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   of [sqlite3_com
128f0 70 6c 65 74 65 28 29 5d 20 6f 72 20 5b 73 71 6c  plete()] or [sql
12900 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
12910 29 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20  )] then the.**  
12920 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20          routine 
12930 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51  shall return [SQ
12940 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
12950 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
12960 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 32 7d 20 54  **.** {A10512} T
12970 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
12980 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
12990 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
129a0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
129b0 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
129c0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35  ing..**.** {A105
129d0 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f  13} The input to
129e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
129f0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
12a00 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
12a10 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54  d.**          UT
12a20 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
12a30 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
12a40 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
12a50 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
12a60 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
12a70 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
12a80 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
12a90 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
12aa0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
12ab0 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
12ac0 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
12ad0 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30 7d 20  Errors {H12310} 
12ae0 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S40400>.**.** T
12af0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
12b00 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
12b10 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
12b20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
12b30 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
12b40 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
12b50 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
12b60 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  le that another 
12b70 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
12b80 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
12b90 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 75  .**.** If the bu
12ba0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
12bb0 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
12bc0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
12bd0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
12be0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
12bf0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
12c00 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
12c10 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20  he lock. If the 
12c20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
12c30 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
12c40 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
12c50 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
12c60 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
12c70 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ts..**.** The fi
12c80 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
12c90 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61  the handler is a
12ca0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
12cb0 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
12cc0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
12cd0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
12ce0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
12cf0 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  r().  The second
12d00 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
12d10 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  the handler call
12d20 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
12d30 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
12d40 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
12d50 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
12d60 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
12d70 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 49  ocking event.  I
12d80 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
12d90 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
12da0 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
12db0 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
12dc0 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
12dd0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
12de0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
12df0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
12e00 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
12e10 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20  returned..** If 
12e20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
12e30 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
12e40 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
12e50 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
12e60 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
12e70 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
12e80 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
12e90 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
12ea0 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
12eb0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
12ec0 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
12ed0 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
12ee0 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
12ef0 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
12f00 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69  tention. If SQLi
12f10 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
12f20 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
12f30 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
12f40 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
12f50 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
12f60 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
12f70 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12f80 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
12f90 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
12fa0 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  D] instead of in
12fb0 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20  voking the busy 
12fc0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
12fd0 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
12fe0 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
12ff0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
13000 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
13010 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
13020 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
13030 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
13040 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
13050 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
13060 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
13070 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
13080 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
13090 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
130a0 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
130b0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
130c0 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
130d0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
130e0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
130f0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
13100 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
13110 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
13120 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
13130 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
13140 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
13150 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
13160 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
13170 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
13180 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
13190 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
131a0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
131b0 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
131c0 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
131d0 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
131e0 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
131f0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
13200 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
13210 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
13220 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
13230 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
13240 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  eed..**.** The d
13250 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
13260 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
13270 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
13280 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
13290 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
132a0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
132b0 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  D].** when SQLit
132c0 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
132d0 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
132e0 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
132f0 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
13300 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
13310 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
13320 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
13330 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
13340 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
13350 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
13360 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
13370 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
13380 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
13390 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
133a0 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
133b0 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
133c0 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
133d0 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
133e0 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
133f0 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
13400 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c    If it is unabl
13410 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65  e to promote the
13420 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20   lock, then the 
13430 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63  in-memory.** cac
13440 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20  he will be left 
13450 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65  in an inconsiste
13460 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20  nt state and so 
13470 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
13480 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72  e is promoted fr
13490 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c  om the relativel
134a0 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45  y benign [SQLITE
134b0 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65  _BUSY] to.** the
134c0 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51   more severe [SQ
134d0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
134e0 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72  ED].  This error
134f0 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
13500 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
13510 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
13520 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
13530 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
13540 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
13550 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
13560 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
13570 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
13580 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
13590 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
135a0 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
135b0 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
135c0 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
135d0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20  **.** There can 
135e0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
135f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
13600 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
13610 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
13620 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
13630 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
13640 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
13650 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
13660 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65  t handler.  Note
13670 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
13680 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
13690 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
136a0 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
136b0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
136c0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
136d0 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
136e0 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
136f0 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
13700 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
13710 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
13720 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
13730 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41  busy handler.  A
13740 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
13750 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
13760 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
13770 0a 2a 2a 20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  .** .** INVARIAN
13780 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31  TS:.**.** {H1231
13790 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
137a0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 43  busy_handler(D,C
137b0 2c 41 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  ,A)] function sh
137c0 61 6c 6c 20 72 65 70 6c 61 63 65 0a 2a 2a 20 20  all replace.**  
137d0 20 20 20 20 20 20 20 20 62 75 73 79 20 63 61 6c          busy cal
137e0 6c 62 61 63 6b 20 69 6e 20 74 68 65 20 5b 64 61  lback in the [da
137f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13800 6e 5d 20 44 20 77 69 74 68 20 61 20 6e 65 77 0a  n] D with a new.
13810 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 6e 65  **          a ne
13820 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 43  w busy handler C
13830 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e   and application
13840 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 41 2e   data pointer A.
13850 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 32 7d 20  .**.** {H12312} 
13860 4e 65 77 6c 79 20 63 72 65 61 74 65 64 20 5b 64  Newly created [d
13870 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13880 6f 6e 73 5d 20 73 68 61 6c 6c 20 68 61 76 65 20  ons] shall have 
13890 61 20 62 75 73 79 0a 2a 2a 20 20 20 20 20 20 20  a busy.**       
138a0 20 20 20 68 61 6e 64 6c 65 72 20 6f 66 20 4e 55     handler of NU
138b0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31  LL..**.** {H1231
138c0 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d  4} When two or m
138d0 6f 72 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ore [database co
138e0 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61 72 65  nnections] share
138f0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b   a.**          [
13900 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
13910 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20 63 6f  hared_cache | co
13920 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20  mmon cache],.** 
13930 20 20 20 20 20 20 20 20 20 74 68 65 20 62 75 73           the bus
13940 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68  y handler for th
13950 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
13960 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20  ction currently 
13970 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  using.**        
13980 20 20 74 68 65 20 63 61 63 68 65 20 73 68 61 6c    the cache shal
13990 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  l be invoked whe
139a0 6e 20 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f  n the cache enco
139b0 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a  unters a lock..*
139c0 2a 0a 2a 2a 20 7b 48 31 32 33 31 36 7d 20 49 66  *.** {H12316} If
139d0 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
139e0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
139f0 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20   zero, then the 
13a00 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
13a10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61  .**          tha
13a20 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c  t provoked the l
13a30 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20 73 68 61  ocking event sha
13a40 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
13a50 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_BUSY]..**.** {
13a60 48 31 32 33 31 38 7d 20 53 51 4c 69 74 65 20 73  H12318} SQLite s
13a70 68 61 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65  hall invokes the
13a80 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69   busy handler wi
13a90 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
13aa0 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20   which.**       
13ab0 20 20 20 61 72 65 20 61 20 63 6f 70 79 20 6f 66     are a copy of
13ac0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 73 75 70   the pointer sup
13ad0 70 6c 69 65 64 20 62 79 20 74 68 65 20 33 72 64  plied by the 3rd
13ae0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
13af0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
13b00 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
13b10 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f  )] and a count o
13b20 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
13b30 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  prior.**        
13b40 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66    invocations of
13b50 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
13b60 72 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c  r for the same l
13b70 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a  ocking event..**
13b80 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
13b90 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33 31 39 7d 20  .**.** {A12319} 
13ba0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
13bb0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
13bc0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
13bd0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
13be0 20 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73    or [prepared s
13bf0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
13c00 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
13c10 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20  handler..*/.int 
13c20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
13c30 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
13c40 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
13c50 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
13c60 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
13c70 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 48   Busy Timeout {H
13c80 31 32 33 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a  12340} <S40410>.
13c90 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
13ca0 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
13cb0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
13cc0 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
13cd0 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
13ce0 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
13cf0 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
13d00 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
13d10 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c  cked.  The handl
13d20 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
13d30 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
13d40 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
13d50 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
13d60 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
13d70 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
13d80 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 74 65 72  . {H12343} After
13d90 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
13da0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
13db0 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
13dc0 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
13dd0 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
13de0 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
13df0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
13e00 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
13e10 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
13e20 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  ** Calling this 
13e30 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
13e40 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
13e50 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
13e60 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
13e70 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
13e80 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  rs..**.** There 
13e90 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
13ea0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
13eb0 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
13ec0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
13ed0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20  connection] any 
13ee0 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
13ef0 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
13f00 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
13f10 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
13f20 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
13f30 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
13f40 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
13f50 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
13f60 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
13f70 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
13f80 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
13f90 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34  TS:.**.** {H1234
13fa0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
13fb0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
13fc0 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 6f  function shall o
13fd0 76 65 72 72 69 64 65 20 61 6e 79 20 70 72 69 6f  verride any prio
13fe0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
13ff0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
14000 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  out()] or [sqlit
14010 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
14020 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  )] setting.**   
14030 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61         on the sa
14040 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
14050 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  nection]..**.** 
14060 7b 48 31 32 33 34 33 7d 20 49 66 20 74 68 65 20  {H12343} If the 
14070 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
14080 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
14090 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c 65 73  imeout()] is les
140a0 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  s than.**       
140b0 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a     or equal to z
140c0 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 62 75  ero, then the bu
140d0 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c  sy handler shall
140e0 20 62 65 20 63 6c 65 61 72 65 64 20 73 6f 20 74   be cleared so t
140f0 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
14100 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6c  all subsequent l
14110 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20 69 6d  ocking events im
14120 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e  mediately return
14130 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
14140 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 34 7d 20 49  **.** {H12344} I
14150 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
14160 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
14170 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
14180 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a  is a positive.**
14190 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
141a0 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73 79 20   N, then a busy 
141b0 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65  handler shall be
141c0 20 73 65 74 20 74 68 61 74 20 72 65 70 65 61 74   set that repeat
141d0 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20  edly calls.**   
141e0 20 20 20 20 20 20 20 74 68 65 20 78 53 6c 65 65         the xSlee
141f0 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20 74 68  p() method in th
14200 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  e [sqlite3_vfs |
14210 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 5d 20   VFS interface] 
14220 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20  until.**        
14230 20 20 65 69 74 68 65 72 20 74 68 65 20 6c 6f 63    either the loc
14240 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e 74 69  k clears or unti
14250 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69 76 65  l the cumulative
14260 20 73 6c 65 65 70 20 74 69 6d 65 0a 2a 2a 20 20   sleep time.**  
14270 20 20 20 20 20 20 20 20 72 65 70 6f 72 74 65 64          reported
14280 20 62 61 63 6b 20 62 79 20 78 53 6c 65 65 70 28   back by xSleep(
14290 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c  ) exceeds N mill
142a0 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74  iseconds..*/.int
142b0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
142c0 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
142d0 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
142e0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
142f0 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
14300 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
14310 65 73 20 7b 48 31 32 33 37 30 7d 20 3c 53 31 30  es {H12370} <S10
14320 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  000>.**.** Defin
14330 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
14340 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
14350 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
14360 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
14370 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
14380 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
14390 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
143a0 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
143b0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
143c0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
143d0 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
143e0 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
143f0 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
14400 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
14410 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
14420 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
14430 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
14440 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
14450 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
14460 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
14470 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
14480 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
14490 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
144a0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
144b0 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
144c0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
144d0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
144e0 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
144f0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
14500 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
14510 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
14520 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
14530 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
14540 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
14550 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
14560 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
14570 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
14580 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
14590 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
145a0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
145b0 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
145c0 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
145d0 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
145e0 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
145f0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
14600 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
14610 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
14620 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
14630 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
14640 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
14650 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
14660 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
14670 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
14680 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
14690 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
146a0 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
146b0 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
146c0 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
146d0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
146e0 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
146f0 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
14700 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
14710 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
14720 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
14730 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
14740 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
14750 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61  e()]..**.** As a
14760 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
14770 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
14780 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
14790 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
147a0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
147b0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
147c0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
147d0 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
147e0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
147f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14800 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
14810 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
14820 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
14830 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
14840 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
14850 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
14860 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
14870 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
14880 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
14890 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
148a0 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
148b0 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
148c0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
148d0 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
148e0 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
148f0 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
14900 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
14910 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
14920 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
14930 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
14940 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
14950 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
14960 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
14970 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
14980 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
14990 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
149a0 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
149b0 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
149c0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
149d0 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
149e0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
149f0 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
14a00 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
14a10 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
14a20 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14a30 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
14a40 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
14a50 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
14a60 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
14a70 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
14a80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
14a90 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
14aa0 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
14ab0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
14ac0 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
14ad0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
14ae0 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
14af0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
14b00 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
14b10 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  nd parameter.  I
14b20 74 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  t returns a resu
14b30 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
14b40 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
14b50 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
14b60 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
14b70 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  er the calling f
14b80 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  unction has fini
14b90 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 72  shed using the r
14ba0 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64  esult, it should
14bb0 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69  .** pass the poi
14bc0 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65 73 75  nter to the resu
14bd0 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69  lt table to sqli
14be0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14bf0 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
14c00 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
14c10 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
14c20 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
14c30 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
14c40 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14c50 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
14c60 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
14c70 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
14c80 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
14c90 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
14ca0 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
14cb0 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
14cc0 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
14cd0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
14ce0 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
14cf0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
14d00 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
14d10 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
14d20 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14d30 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
14d40 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
14d50 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
14d60 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
14d70 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
14d80 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
14d90 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
14da0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
14db0 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
14dc0 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
14dd0 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
14de0 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
14df0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
14e00 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
14e10 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
14e20 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
14e30 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
14e40 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
14e50 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
14e60 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
14e70 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
14e80 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
14e90 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
14ea0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
14eb0 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  de()] or [sqlite
14ec0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a  3_errmsg()]..**.
14ed0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
14ee0 2a 0a 2a 2a 20 7b 48 31 32 33 37 31 7d 20 49 66  *.** {H12371} If
14ef0 20 61 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f   a [sqlite3_get_
14f00 74 61 62 6c 65 28 29 5d 20 66 61 69 6c 73 20 61  table()] fails a
14f10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14f20 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  on, then.**     
14f30 20 20 20 20 20 69 74 20 73 68 61 6c 6c 20 66 72       it shall fr
14f40 65 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  ee the result ta
14f50 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72  ble under constr
14f60 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 20 74 68  uction, abort th
14f70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75  e.**          qu
14f80 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20  ery in process, 
14f90 73 6b 69 70 20 61 6e 79 20 73 75 62 73 65 71 75  skip any subsequ
14fa0 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65 74  ent queries, set
14fb0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
14fc0 20 2a 70 61 7a 52 65 73 75 6c 74 20 6f 75 74 70   *pazResult outp
14fd0 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55  ut pointer to NU
14fe0 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  LL and return [S
14ff0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
15000 0a 2a 2a 20 7b 48 31 32 33 37 33 7d 20 49 66 20  .** {H12373} If 
15010 74 68 65 20 70 6e 43 6f 6c 75 6d 6e 20 70 61 72  the pnColumn par
15020 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
15030 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
15040 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20  is not NULL.**  
15050 20 20 20 20 20 20 20 20 74 68 65 6e 20 61 20 73          then a s
15060 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
15070 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
15080 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73 68  _get_table()] sh
15090 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
150a0 77 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72  write the number
150b0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
150c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
150d0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65  esult set of the
150e0 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 43   query into *pnC
150f0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  olumn..**.** {H1
15100 32 33 37 34 7d 20 49 66 20 74 68 65 20 70 6e 52  2374} If the pnR
15110 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ow parameter to 
15120 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
15130 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c  le()] is not NUL
15140 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  L.**          th
15150 65 6e 20 61 20 73 75 63 63 65 73 73 66 75 6c 20  en a successful 
15160 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
15170 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
15180 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20  ()] shall.**    
15190 20 20 20 20 20 20 77 72 69 74 65 73 20 74 68 65        writes the
151a0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
151b0 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
151c0 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66     result set of
151d0 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20   the query into 
151e0 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48  *pnRow..**.** {H
151f0 31 32 33 37 36 7d 20 41 20 73 75 63 63 65 73 73  12376} A success
15200 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
15210 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  f [sqlite3_get_t
15220 61 62 6c 65 28 29 5d 20 74 68 61 74 20 63 6f 6d  able()] that com
15230 70 75 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  putes.**        
15240 20 20 4e 20 72 6f 77 73 20 6f 66 20 72 65 73 75    N rows of resu
15250 6c 74 20 77 69 74 68 20 43 20 63 6f 6c 75 6d 6e  lt with C column
15260 73 20 70 65 72 20 72 6f 77 20 73 68 61 6c 6c 20  s per row shall 
15270 6d 61 6b 65 20 2a 70 61 7a 52 65 73 75 6c 74 0a  make *pazResult.
15280 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e  **          poin
15290 74 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  t to an array of
152a0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 28 4e 2b   pointers to (N+
152b0 31 29 2a 43 20 73 74 72 69 6e 67 73 20 77 68 65  1)*C strings whe
152c0 72 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  re the first.** 
152d0 20 20 20 20 20 20 20 20 20 43 20 73 74 72 69 6e           C strin
152e0 67 73 20 61 72 65 20 63 6f 6c 75 6d 6e 20 6e 61  gs are column na
152f0 6d 65 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20  mes as obtained 
15300 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20  from.**         
15310 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
15320 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 74 68 65  _name()] and the
15330 20 72 65 73 74 20 61 72 65 20 63 6f 6c 75 6d 6e   rest are column
15340 20 72 65 73 75 6c 74 20 76 61 6c 75 65 73 0a 2a   result values.*
15350 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69  *          obtai
15360 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
15370 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
15380 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 39 7d  ..**.** {H12379}
15390 20 54 68 65 20 76 61 6c 75 65 73 20 69 6e 20 74   The values in t
153a0 68 65 20 70 61 7a 52 65 73 75 6c 74 20 61 72 72  he pazResult arr
153b0 61 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ay returned by [
153c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
153d0 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  e()].**         
153e0 20 73 68 61 6c 6c 20 72 65 6d 61 69 6e 20 76 61   shall remain va
153f0 6c 69 64 20 75 6e 74 69 6c 20 63 6c 65 61 72 65  lid until cleare
15400 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
15410 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
15420 2a 2a 20 7b 48 31 32 33 38 32 7d 20 57 68 65 6e  ** {H12382} When
15430 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
15440 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69   during evaluati
15450 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67  on of [sqlite3_g
15460 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20  et_table()].**  
15470 20 20 20 20 20 20 20 20 74 68 65 20 66 75 6e 63          the func
15480 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 2a  tion shall set *
15490 70 61 7a 52 65 73 75 6c 74 20 74 6f 20 4e 55 4c  pazResult to NUL
154a0 4c 2c 20 77 72 69 74 65 20 61 6e 20 65 72 72 6f  L, write an erro
154b0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
154c0 20 20 20 20 20 20 69 6e 74 6f 20 6d 65 6d 6f 72        into memor
154d0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
154e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
154f0 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 20 20 20 20  )], make.**     
15500 20 20 20 20 20 2a 2a 70 7a 45 72 72 6d 73 67 20       **pzErrmsg 
15510 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 65 72  point to that er
15520 72 6f 72 20 6d 65 73 73 61 67 65 2c 20 61 6e 64  ror message, and
15530 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 20 20 20   return a.**    
15540 20 20 20 20 20 20 61 70 70 72 6f 70 72 69 61 74        appropriat
15550 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
15560 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
15570 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
15580 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
15590 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
155a0 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
155b0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
155c0 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
155d0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
155e0 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
155f0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
15600 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
15610 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
15620 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
15630 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
15640 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
15650 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
15660 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
15670 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
15680 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
15690 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
156a0 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
156b0 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
156c0 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
156d0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
156e0 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
156f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
15700 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
15710 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
15720 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d  nctions {H17400}
15730 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30   <S70000><S20000
15740 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
15750 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61  utines are worka
15760 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
15770 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
15780 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
15790 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
157a0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
157b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70  * The sqlite3_mp
157c0 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
157d0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
157e0 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
157f0 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
15800 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
15810 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
15820 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
15830 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
15840 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
15850 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
15860 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
15870 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
15880 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74  e()].  Both rout
15890 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
158a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
158b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
158c0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
158d0 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
158e0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
158f0 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
15900 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49   string..**.** I
15910 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  n sqlite3_snprin
15920 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
15930 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
15940 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
15950 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
15960 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
15970 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
15980 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
15990 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
159a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
159b0 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
159c0 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
159d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
159e0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
159f0 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
15a00 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
15a10 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
15a20 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
15a30 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  .  This is an.**
15a40 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
15a50 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
15a60 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
15a70 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
15a80 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
15a90 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73  ility.  Note als
15aa0 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
15ab0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
15ac0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
15ad0 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
15ae0 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
15af0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
15b00 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
15b10 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
15b20 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20  ffer.  We admit 
15b30 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
15b40 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
15b50 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
15b60 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
15b70 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
15b80 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
15b90 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
15ba0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
15bb0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
15bc0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
15bd0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
15be0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f  ity..**.** As lo
15bf0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
15c00 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
15c10 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
15c20 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
15c30 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
15c40 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
15c50 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
15c60 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72  inated.  The fir
15c70 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
15c80 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
15c90 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
15ca0 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
15cb0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
15cc0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
15cd0 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
15ce0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
15cf0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
15d00 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
15d10 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
15d20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
15d30 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
15d40 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
15d50 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
15d60 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
15d70 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
15d80 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
15d90 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
15da0 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
15db0 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
15dc0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
15dd0 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
15de0 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
15df0 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64   "%q", "%Q", and
15e00 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
15e10 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69  *.** The %q opti
15e20 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
15e30 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
15e40 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74  titutes a null-t
15e50 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
15e60 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67  ing from the arg
15e70 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74  ument list.  But
15e80 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73   %q also doubles
15e90 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72   every '\'' char
15ea0 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20  acter..** %q is 
15eb0 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65  designed for use
15ec0 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67   inside a string
15ed0 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f   literal.  By do
15ee0 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
15ef0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
15f00 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
15f10 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
15f20 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
15f30 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
15f40 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
15f50 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
15f60 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
15f70 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
15f80 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
15f90 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
15fa0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
15fb0 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
15fc0 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
15fd0 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
15fe0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
15ff0 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
16000 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
16010 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
16020 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
16030 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
16040 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
16050 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
16060 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
16070 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
16080 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
16090 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
160a0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
160b0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
160c0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
160d0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
160e0 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
160f0 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
16100 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
16110 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
16120 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
16130 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
16140 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
16150 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
16160 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
16170 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
16180 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
16190 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
161a0 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
161b0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
161c0 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
161d0 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
161e0 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
161f0 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
16200 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
16210 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
16220 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
16230 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
16240 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
16250 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
16260 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
16270 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
16280 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
16290 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
162a0 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
162b0 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
162c0 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
162d0 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
162e0 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
162f0 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
16300 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
16310 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
16320 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20  l..**.** The %Q 
16330 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
16340 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
16350 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
16360 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
16370 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
16380 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
16390 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
163a0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
163b0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
163c0 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
163d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
163e0 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
163f0 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
16400 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
16410 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20  uotes) in place 
16420 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e  of the %Q option
16430 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  .  So, for examp
16440 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
16450 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
16460 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
16470 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
16480 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
16490 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
164a0 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
164b0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
164c0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
164d0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
164e0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
164f0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
16500 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
16510 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
16520 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
16530 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
16540 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
16550 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
16560 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
16570 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
16580 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
16590 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
165a0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78   option works ex
165b0 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20  actly like "%s" 
165c0 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
165d0 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
165e0 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
165f0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
16600 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
16610 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
16620 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
16630 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
16640 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a  string. {END}.**
16650 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
16660 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 33 7d 20 20  **.** {H17403}  
16670 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  The [sqlite3_mpr
16680 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c  intf()] and [sql
16690 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d  ite3_vmprintf()]
166a0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20   interfaces.**  
166b0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
166c0 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20  either pointers 
166d0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
166e0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
166f0 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20   held in.**     
16700 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74        memory obt
16710 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
16720 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
16730 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69   NULL pointers i
16740 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61  f.**           a
16750 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
16760 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c  3_malloc()] fail
16770 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 36  s..**.** {H17406
16780 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
16790 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65  snprintf()] inte
167a0 72 66 61 63 65 20 77 72 69 74 65 73 20 61 20 7a  rface writes a z
167b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
167c0 2a 20 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  *           UTF-
167d0 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68  8 string into th
167e0 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64  e buffer pointed
167f0 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
16800 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  d parameter.**  
16810 20 20 20 20 20 20 20 20 20 70 72 6f 76 69 64 65           provide
16820 64 20 74 68 61 74 20 74 68 65 20 66 69 72 73 74  d that the first
16830 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 67 72   parameter is gr
16840 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e  eater than zero.
16850 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 37 7d 20  .**.** {H17407} 
16860 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e   The [sqlite3_sn
16870 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66  printf()] interf
16880 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69  ace does not wri
16890 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20  te slots of.**  
168a0 20 20 20 20 20 20 20 20 20 69 74 73 20 6f 75 74           its out
168b0 70 75 74 20 62 75 66 66 65 72 20 28 74 68 65 20  put buffer (the 
168c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
168d0 29 20 6f 75 74 73 69 64 65 20 74 68 65 20 72 61  ) outside the ra
168e0 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nge.**          
168f0 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d   of 0 through N-
16900 31 20 28 77 68 65 72 65 20 4e 20 69 73 20 74 68  1 (where N is th
16910 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
16920 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  r).**           
16930 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
16940 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
16950 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
16960 20 20 20 20 72 65 71 75 65 73 74 65 64 20 62 79      requested by
16970 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63   the format spec
16980 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68  ification..*/.ch
16990 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
169a0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
169b0 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
169c0 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
169d0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
169e0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
169f0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
16a00 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
16a10 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
16a20 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
16a30 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
16a40 73 74 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53  stem {H17300} <S
16a50 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20000>.**.** The
16a60 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73   SQLite core  us
16a70 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
16a80 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
16a90 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
16aa0 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
16ab0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
16ac0 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
16ad0 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
16ae0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
16af0 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
16b00 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
16b10 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
16b20 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
16b30 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
16b40 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
16b50 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
16b60 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
16b70 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c   The sqlite3_mal
16b80 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
16b90 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
16ba0 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
16bb0 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
16bc0 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
16bd0 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
16be0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
16bf0 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
16c00 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
16c10 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
16c20 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
16c30 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
16c40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
16c50 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
16c60 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
16c70 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
16c80 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
16c90 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
16ca0 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
16cb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
16cc0 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c  *.** Calling sql
16cd0 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
16ce0 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
16cf0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
16d00 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
16d10 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
16d20 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
16d30 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
16d40 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
16d50 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
16d60 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
16d70 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
16d80 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
16d90 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
16da0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
16db0 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
16dc0 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
16dd0 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
16de0 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
16df0 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
16e00 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
16e10 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
16e20 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
16e30 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
16e40 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
16e50 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
16e60 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
16e70 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
16e80 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
16e90 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
16ea0 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
16eb0 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
16ec0 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
16ed0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
16ee0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
16ef0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
16f00 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
16f10 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
16f20 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
16f30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16f40 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
16f50 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  loc()..**.** The
16f60 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
16f70 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
16f80 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
16f90 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
16fa0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
16fb0 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
16fc0 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  tes, where N is 
16fd0 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  the.** second pa
16fe0 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65  rameter.  The me
16ff0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
17000 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73  to be resized is
17010 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
17020 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65  rameter.  If the
17030 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
17040 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
17050 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
17060 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
17070 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
17080 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
17090 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
170a0 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
170b0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
170c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
170d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
170e0 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64  ** If the second
170f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
17100 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
17110 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
17120 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
17130 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
17140 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
17150 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
17160 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65  e3_free(P) where
17170 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20   P is the first 
17180 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
17190 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
171a0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ** sqlite3_reall
171b0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
171c0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
171d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
171e0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
171f0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
17200 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
17210 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
17220 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20  vailable..** If 
17230 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
17240 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
17250 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
17260 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
17270 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
17280 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
17290 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
172a0 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
172b0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
172c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
172d0 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
172e0 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
172f0 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
17300 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
17310 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
17320 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
17330 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
17340 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d  d..**.** The mem
17350 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
17360 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17370 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
17380 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
17390 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
173a0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
173b0 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44  e boundary. {END
173c0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  }.**.** The defa
173d0 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ult implementati
173e0 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79  on of the memory
173f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
17400 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68  ystem uses.** th
17410 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  e malloc(), real
17420 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
17430 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
17440 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
17450 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d  ary..** {H17382}
17460 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c   However, if SQL
17470 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
17480 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
17490 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c  TE_MEMORY_SIZE=<
174a0 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70  i>NNN</i> C prep
174b0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 28  rocessor macro (
174c0 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  where <i>NNN</i>
174d0 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65  .** is an intege
174e0 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  r), then SQLite 
174f0 63 72 65 61 74 65 20 61 20 73 74 61 74 69 63 20  create a static 
17500 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73  array of at leas
17510 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  t.** <i>NNN</i> 
17520 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
17530 64 20 75 73 65 73 20 74 68 61 74 20 61 72 72 61  d uses that arra
17540 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  y for all of its
17550 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f   dynamic.** memo
17560 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
17570 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69  eds. {END}  Addi
17580 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  tional memory al
17590 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a  locator options.
175a0 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ** may be added 
175b0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
175c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  es..**.** In SQL
175d0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
175e0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
175f0 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
17600 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
17610 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
17620 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
17630 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
17640 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
17650 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
17660 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
17670 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
17680 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
17690 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
176a0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
176b0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
176c0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
176d0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
176e0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
176f0 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
17700 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
17710 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
17720 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
17730 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
17740 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
17750 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
17760 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
17770 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
17780 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
17790 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
177a0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
177b0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
177c0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
177d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
177e0 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
177f0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
17800 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
17810 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
17820 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
17830 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
17840 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
17850 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  EM]..**.** INVAR
17860 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
17870 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69  7303}  The [sqli
17880 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69  te3_malloc(N)] i
17890 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
178a0 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65   either a pointe
178b0 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
178c0 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63 6b 65    a newly checke
178d0 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 20 61  d-out block of a
178e0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
178f0 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  of memory.**    
17900 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 38         that is 8
17910 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f  -byte aligned, o
17920 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  r it returns NUL
17930 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 62 6c  L if it is unabl
17940 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  e.**           t
17950 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20 72 65  o fulfill the re
17960 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  quest..**.** {H1
17970 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71 6c 69  7304}  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 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
179b0 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  if.**           
179c0 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
179d0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e  r equal to zero.
179e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 35 7d 20  .**.** {H17305} 
179f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 72   The [sqlite3_fr
17a00 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ee(P)] interface
17a10 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79   releases memory
17a20 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20   previously.**  
17a30 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65           returne
17a40 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
17a50 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
17a60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
17a70 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d  ,.**           m
17a80 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c 61 62  aking it availab
17a90 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a  le for reuse..**
17aa0 0a 2a 2a 20 7b 48 31 37 33 30 36 7d 20 20 41 20  .** {H17306}  A 
17ab0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
17ac0 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20  _free(NULL)] is 
17ad0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
17ae0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 30 7d  ..**.** {H17310}
17af0 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
17b00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e  ite3_realloc(0,N
17b10 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  )] is equivalent
17b20 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20   to a call.**   
17b30 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69          to [sqli
17b40 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a  te3_malloc(N)]..
17b50 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 32 7d 20 20  **.** {H17312}  
17b60 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
17b70 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d  e3_realloc(P,0)]
17b80 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
17b90 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  o a call.**     
17ba0 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65        to [sqlite
17bb0 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a  3_free(P)]..**.*
17bc0 2a 20 7b 48 31 37 33 31 35 7d 20 20 54 68 65 20  * {H17315}  The 
17bd0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
17be0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
17bf0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  ()], [sqlite3_re
17c00 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20  alloc()],.**    
17c10 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71 6c 69         and [sqli
17c20 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20  te3_free()] for 
17c30 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72  all of its memor
17c40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64  y allocation and
17c50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 64 65  .**           de
17c60 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
17c70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 38 7d  ..**.** {H17318}
17c80 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72    The [sqlite3_r
17c90 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74  ealloc(P,N)] int
17ca0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
17cb0 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 0a  ither a pointer.
17cc0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
17cd0 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b  a block of check
17ce0 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66  ed-out memory of
17cf0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
17d00 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20  s in size.**    
17d10 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 38         that is 8
17d20 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f  -byte aligned, o
17d30 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
17d40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 31 7d  ..**.** {H17321}
17d50 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    When [sqlite3_
17d60 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65  realloc(P,N)] re
17d70 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  turns a non-NULL
17d80 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72   pointer, it fir
17d90 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  st.**           
17da0 63 6f 70 69 65 73 20 74 68 65 20 66 69 72 73 74  copies the first
17db0 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f 6e 74   K bytes of cont
17dc0 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20  ent from P into 
17dd0 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20 20 20  the newly.**    
17de0 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64         allocated
17df0 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20 4b 20   block, where K 
17e00 69 73 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66  is the lesser of
17e10 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a 65 20   N and the size 
17e20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  of.**           
17e30 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  the buffer P..**
17e40 0a 2a 2a 20 7b 48 31 37 33 32 32 7d 20 20 57 68  .** {H17322}  Wh
17e50 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
17e60 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
17e70 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
17e80 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a  nter, it first.*
17e90 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 6c 65  *           rele
17ea0 61 73 65 73 20 74 68 65 20 62 75 66 66 65 72 20  ases the buffer 
17eb0 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 33  P..**.** {H17323
17ec0 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
17ed0 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
17ee0 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
17ef0 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a 2a 20   buffer P is.** 
17f00 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 6d 6f            not mo
17f10 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65 61 73  dified or releas
17f20 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  ed..**.** ASSUMP
17f30 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
17f40 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69 6e 74  7350}  The point
17f50 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
17f60 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
17f70 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
17f80 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20 20  alloc()].**     
17f90 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 65 69        must be ei
17fa0 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
17fb0 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
17fc0 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
17fd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 6e  .**           in
17fe0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
17ff0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
18000 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
18010 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
18020 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74  **           not
18030 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
18040 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35  ed..**.** {A1735
18050 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  1}  The applicat
18060 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
18070 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
18080 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  art of.**       
18090 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d      a block of m
180a0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
180b0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
180c0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
180d0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65      [sqlite3_fre
180e0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
180f0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
18100 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
18110 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
18120 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
18130 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
18140 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
18150 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
18160 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
18170 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
18180 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20 3c 53  tics {H17370} <S
18190 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  30210>.**.** SQL
181a0 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
181b0 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
181c0 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
181d0 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
181e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
181f0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
18200 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
18210 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
18220 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
18230 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
18240 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
18250 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
18260 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  system..**.** IN
18270 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
18280 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b 73 71  {H17371} The [sq
18290 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
182a0 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
182b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
182c0 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20  of bytes.**     
182d0 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79 20 63       of memory c
182e0 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
182f0 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
18300 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
18310 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20 54 68  *.** {H17373} Th
18320 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
18330 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
18340 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
18350 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20 20  he maximum.**   
18360 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
18370 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
18380 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
18390 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
183a0 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61  k.**          wa
183b0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a  s last reset..**
183c0 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54 68 65  .** {H17374} The
183d0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
183e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
183f0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
18400 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
18410 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
18420 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
18430 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
18440 20 20 20 20 20 20 20 20 20 20 61 64 64 65 64 20            added 
18450 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
18460 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
18470 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
18480 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  oc()],.**       
18490 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68     but not overh
184a0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
184b0 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
184c0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
184d0 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69  *          routi
184e0 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
184f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
18500 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  call..**.** {H17
18510 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20  375} The memory 
18520 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
18530 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
18540 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
18550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
18560 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
18570 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
18580 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
18590 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
185a0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
185b0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
185c0 20 74 72 75 65 2e 20 20 54 68 65 20 76 61 6c 75   true.  The valu
185d0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20  e returned.**   
185e0 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74         by [sqlit
185f0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
18600 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
18610 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
18620 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 6f 72  *          prior
18630 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
18640 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
18650 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
18660 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
18670 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
18680 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
18690 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
186a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
186b0 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
186c0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
186d0 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30  r {H17390} <S200
186e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  00>.**.** SQLite
186f0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
18700 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
18710 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
18720 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
18730 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
18740 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20 77   random ROWIDs w
18750 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
18760 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
18770 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
18780 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
18790 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
187a0 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 52 4e   ROWID.  The PRN
187b0 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
187c0 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
187d0 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
187e0 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
187f0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
18800 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
18810 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
18820 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
18830 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
18840 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
18850 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74  *.** A call to t
18860 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
18870 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
18880 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
18890 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68  ffer P..**.** Th
188a0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
188b0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
188c0 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
188d0 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
188e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
188f0 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
18900 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
18910 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
18920 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
18930 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
18940 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
18950 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
18960 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62  t..** On all sub
18970 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
18980 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
18990 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
189a0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
189b0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
189c0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
189d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
189e0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
189f0 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ethod..**.** INV
18a00 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
18a10 48 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c  H17392} The [sql
18a20 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
18a30 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,P)] interface 
18a40 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f  writes N bytes o
18a50 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69  f.**          hi
18a60 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
18a70 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  o-randomness int
18a80 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76  o buffer P..*/.v
18a90 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
18aa0 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
18ab0 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
18ac0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
18ad0 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
18ae0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ion Callbacks {H
18af0 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a  12500} <S70100>.
18b00 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
18b10 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61  ne registers a a
18b20 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18b30 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
18b40 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
18b50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
18b60 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
18b70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
18b80 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
18b90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
18ba0 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
18bb0 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
18bc0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
18bd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18be0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
18bf0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
18c00 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
18c10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
18c20 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
18c30 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
18c40 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a  ].  At various.*
18c50 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
18c60 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
18c70 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
18c80 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
18c90 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
18ca0 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
18cb0 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
18cc0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
18cd0 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
18ce0 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
18cf0 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68  are allowed.  Th
18d00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18d10 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
18d20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
18d30 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
18d40 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
18d50 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
18d60 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
18d70 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
18d80 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
18d90 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
18da0 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
18db0 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
18dc0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
18dd0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
18de0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
18df0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
18e00 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68  an error.  If th
18e10 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18e20 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
18e30 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
18e40 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
18e50 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
18e60 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
18e70 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
18e80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18e90 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
18ea0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
18eb0 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
18ec0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
18ed0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
18ee0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
18ef0 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
18f00 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
18f10 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
18f20 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
18f30 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
18f40 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65  is ok.  When the
18f50 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
18f60 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
18f70 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
18f80 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
18f90 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
18fa0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
18fb0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
18fc0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
18fd0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
18fe0 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
18ff0 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
19000 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20  denied.  If the 
19010 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
19020 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
19030 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
19040 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
19050 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
19060 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
19070 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
19080 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
19090 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
190a0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
190b0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
190c0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
190d0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
190e0 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
190f0 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
19100 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
19110 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
19120 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
19130 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
19140 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
19150 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
19160 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
19170 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
19180 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
19190 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
191a0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
191b0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
191c0 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
191d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
191e0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
191f0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
19200 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64  face. The second
19210 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
19220 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
19230 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
19240 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
19250 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
19260 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
19270 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
19280 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
19290 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  . The third thro
192a0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
192b0 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
192c0 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
192d0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
192e0 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
192f0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
19300 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
19310 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
19320 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
19330 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
19340 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
19350 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
19360 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
19370 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
19380 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
19390 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
193a0 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
193b0 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
193c0 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
193d0 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
193e0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
193f0 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
19400 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
19410 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
19420 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
19430 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
19440 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
19450 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
19460 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
19470 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
19480 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
19490 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
194a0 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
194b0 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
194c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
194d0 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
194e0 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
194f0 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
19500 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
19510 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
19520 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
19530 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
19540 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
19550 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
19560 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
19570 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19580 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
19590 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
195a0 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
195b0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
195c0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
195d0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
195e0 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
195f0 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
19600 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
19610 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
19620 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
19630 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
19640 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
19650 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
19660 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
19670 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
19680 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
19690 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
196a0 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
196b0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
196c0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
196d0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
196e0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
196f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19700 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
19710 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
19720 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
19730 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
19740 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
19750 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68  all.  Disable th
19760 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
19770 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
19780 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
19790 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
197a0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
197b0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
197c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
197d0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
197e0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
197f0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
19800 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19810 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
19820 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
19830 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
19840 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
19850 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
19860 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
19870 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
19880 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
19890 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
198a0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
198b0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
198c0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
198d0 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** When [sqlite3
198e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
198f0 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
19900 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
19910 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
19920 6d 69 67 68 74 20 62 65 20 72 65 70 72 65 70 61  might be reprepa
19930 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
19940 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
19950 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
19960 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
19970 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19980 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
19990 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
199a0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
199b0 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
199c0 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
199d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
199e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  )]..**.** Note t
199f0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
19a00 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
19a10 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
19a20 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
19a30 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
19a40 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
19a50 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
19a60 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
19a70 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
19a80 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
19a90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
19aa0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
19ab0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20  .**.** {H12501} 
19ac0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
19ad0 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e  _authorizer(D,..
19ae0 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  .)] interface re
19af0 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20  gisters a.**    
19b00 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72        authorizer
19b10 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64   callback with d
19b20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19b30 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  on D..**.** {H12
19b40 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69  502} The authori
19b50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
19b60 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
19b70 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
19b80 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20            being 
19b90 70 61 72 73 65 65 64 20 61 6e 64 20 63 6f 6d 70  parseed and comp
19ba0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  iled..**.** {H12
19bb0 35 30 33 7d 20 49 66 20 74 68 65 20 61 75 74 68  503} If the auth
19bc0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
19bd0 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75  returns any valu
19be0 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20  e other than.** 
19bf0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
19c00 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
19c10 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
19c20 45 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a  E_DENY], then.**
19c30 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61 70            the ap
19c40 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65 72 66  plication interf
19c50 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20 63 61  ace call that ca
19c60 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  used.**         
19c70 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
19c80 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20  callback to run 
19c90 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20  shall fail with 
19ca0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
19cb0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72  SQLITE_ERROR] er
19cc0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20  ror code and an 
19cd0 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
19ce0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
19cf0 20 7b 48 31 32 35 30 34 7d 20 57 68 65 6e 20 74   {H12504} When t
19d00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19d10 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
19d20 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20  SQLITE_OK], the 
19d30 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20  operation.**    
19d40 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64 20        described 
19d50 69 73 20 70 72 6f 63 65 73 73 65 64 20 6e 6f 72  is processed nor
19d60 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  mally..**.** {H1
19d70 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61  2505} When the a
19d80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19d90 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
19da0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
19db0 20 20 20 20 20 20 20 20 20 20 61 70 70 6c 69 63            applic
19dc0 61 74 69 6f 6e 20 69 6e 74 65 72 66 61 63 65 20  ation interface 
19dd0 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64  call that caused
19de0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
19df0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19e00 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c  back to run shal
19e10 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20  l fail.**       
19e20 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49     with an [SQLI
19e30 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20  TE_ERROR] error 
19e40 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f  code and an erro
19e50 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
19e60 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67        explaining
19e70 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73 20   that access is 
19e80 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  denied..**.** {H
19e90 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75  12506} If the au
19ea0 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74  thorizer code (t
19eb0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
19ec0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
19ed0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  er.**          c
19ee0 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c  allback) is [SQL
19ef0 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68  ITE_READ] and th
19f00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
19f10 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
19f20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
19f30 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20  E_IGNORE], then 
19f40 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
19f50 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
19f60 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  ucted to.**     
19f70 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55       insert a NU
19f80 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
19f90 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
19fa0 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
19fb0 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
19fc0 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b    been read if [
19fd0 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
19fe0 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  een returned..**
19ff0 0a 2a 2a 20 7b 48 31 32 35 30 37 7d 20 49 66 20  .** {H12507} If 
1a000 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1a010 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72  ode (the 2nd par
1a020 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1a030 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20  thorizer.**     
1a040 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69       callback) i
1a050 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72  s anything other
1a060 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45   than [SQLITE_RE
1a070 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  AD], then.**    
1a080 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f        a return o
1a090 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  f [SQLITE_IGNORE
1a0a0 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65  ] has the same e
1a0b0 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45  ffect as [SQLITE
1a0c0 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _DENY]..**.** {H
1a0d0 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 74  12510} The first
1a0e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1a0f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1a100 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
1a110 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
1a120 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
1a130 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
1a140 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1a150 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  r()] interface..
1a160 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54  **.** {H12511} T
1a170 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a180 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
1a190 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
1a1a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
1a1b0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
1a1c0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
1a1d0 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72  pecifies the par
1a1e0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a  ticular action.*
1a1f0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62 65  *          to be
1a200 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
1a210 2a 2a 20 7b 48 31 32 35 31 32 7d 20 54 68 65 20  ** {H12512} The 
1a220 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
1a230 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  xth parameters t
1a240 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
1a250 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  re.**          z
1a260 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1a270 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
1a280 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ain.**          
1a290 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
1a2a0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1a2b0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1a2c0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ized..**.** {H12
1a2d0 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  520} Each call t
1a2e0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  o [sqlite3_set_a
1a2f0 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65  uthorizer()] ove
1a300 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20  rrides.**       
1a310 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c     any previousl
1a320 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68  y installed auth
1a330 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orizer..**.** {H
1a340 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75  12521} A NULL au
1a350 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74  thorizer means t
1a360 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61  hat no authoriza
1a370 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
1a380 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1a390 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  oked..**.** {H12
1a3a0 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74  522} The default
1a3b0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e   authorizer is N
1a3c0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
1a3d0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1a3e0 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
1a3f0 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
1a400 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
1a410 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1a420 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1a430 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
1a440 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
1a450 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a460 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
1a470 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30  rn Codes {H12590
1a480 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <H12500>.**.**
1a490 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1a4a0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1a4b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1a4c0 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
1a4d0 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
1a4e0 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
1a4f0 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
1a500 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
1a510 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
1a520 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
1a530 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
1a540 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
1a550 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
1a560 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1a570 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1a580 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
1a590 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
1a5a0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1a5b0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1a5c0 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1a5d0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1a5e0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1a5f0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1a600 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1a610 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1a620 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1a630 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1a640 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1a650 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1a660 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1a670 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32  es {H12550} <H12
1a680 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  500>.**.** The [
1a690 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1a6a0 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1a6b0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1a6c0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1a6d0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1a6e0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1a6f0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1a700 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1a710 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1a720 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a730 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1a740 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1a750 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1a760 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1a770 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1a780 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1a790 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1a7a0 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1a7b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1a7c0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1a7d0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1a7e0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1a7f0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1a800 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1a810 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1a820 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1a830 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1a840 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1a850 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1a860 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1a870 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1a880 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1a890 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1a8a0 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1a8b0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1a8c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1a8d0 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
1a8e0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1a8f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1a900 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1a910 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1a920 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1a930 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1a940 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70  able.  The 6th p
1a950 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1a960 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1a970 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
1a980 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
1a990 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1a9a0 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1a9b0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1a9c0 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
1a9d0 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
1a9e0 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
1a9f0 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
1aa00 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
1aa10 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  SQL code..**.** 
1aa20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1aa30 2a 20 7b 48 31 32 35 35 31 7d 20 54 68 65 20 73  * {H12551} The s
1aa40 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1aa50 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  to an.**        
1aa60 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
1aa70 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1aa80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d  orizer callback]
1aa90 20 73 68 61 6c 6c 20 62 65 20 61 6e 20 69 6e 74   shall be an int
1aaa0 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  eger.**         
1aab0 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1aac0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d  authorizer code]
1aad0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
1aae0 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20  what action.**  
1aaf0 20 20 20 20 20 20 20 20 69 73 20 62 65 69 6e 67          is being
1ab00 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
1ab10 2a 2a 20 7b 48 31 32 35 35 32 7d 20 54 68 65 20  ** {H12552} The 
1ab20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
1ab30 6d 65 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a  meters to the.**
1ab40 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1ab50 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1ab60 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  r | authorizatio
1ab70 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20  n callback].**  
1ab80 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 62 65          shall be
1ab90 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
1aba0 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
1abb0 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20   which.**       
1abc0 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20     [SQLITE_COPY 
1abd0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  | authorizer cod
1abe0 65 5d 20 69 73 20 75 73 65 64 20 61 73 20 74 68  e] is used as th
1abf0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1ac00 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35  er..**.** {H1255
1ac10 33 7d 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  3} The 5th param
1ac20 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20  eter to the.**  
1ac30 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1ac40 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1ac50 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
1ac60 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20  lback] shall be 
1ac70 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
1ac80 20 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61       of the data
1ac90 62 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22  base (example: "
1aca0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65  main", "temp", e
1acb0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1acc0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35  le..**.** {H1255
1acd0 34 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d  4} The 6th param
1ace0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20  eter to the.**  
1acf0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1ad00 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1ad10 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
1ad20 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20  lback] shall be 
1ad30 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
1ad40 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e 65       of the inne
1ad50 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1ad60 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1ad70 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1ad80 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 61  *          the a
1ad90 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
1ada0 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
1adb0 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
1adc0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
1add0 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c 65            top-le
1ade0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
1adf0 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
1ae00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ae10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
1ae20 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
1ae30 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
1ae40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1ae50 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
1ae60 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
1ae70 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1ae80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1ae90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1aea0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
1aeb0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
1aec0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1aed0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1aee0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1aef0 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
1af00 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
1af10 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1af20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1af30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1af40 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
1af50 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
1af60 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1af70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1af80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1af90 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
1afa0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
1afb0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1afc0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1afd0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1afe0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
1aff0 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
1b000 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1b010 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b020 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1b030 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
1b040 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1b050 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1b060 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b070 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1b080 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
1b090 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1b0a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b0b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b0c0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
1b0d0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
1b0e0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b0f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b100 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b110 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
1b120 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
1b130 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1b140 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b150 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b160 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
1b170 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
1b180 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1b190 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b1a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b1b0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
1b1c0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
1b1d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1b1e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b1f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b200 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
1b210 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
1b220 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b230 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b240 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b250 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
1b260 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
1b270 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1b280 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1b290 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b2a0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
1b2b0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
1b2c0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1b2d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b2e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b2f0 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
1b300 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
1b310 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1b320 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1b330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1b340 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
1b350 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
1b360 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1b370 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b380 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
1b390 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
1b3a0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
1b3b0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1b3c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1b3d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
1b3e0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
1b3f0 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
1b400 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
1b410 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
1b420 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
1b430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1b440 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
1b450 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1b460 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1b470 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
1b480 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1b490 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
1b4a0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1b4b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b4c0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
1b4d0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
1b4e0 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  2   /* NULL     
1b4f0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1b500 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b510 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
1b520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
1b530 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b540 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1b550 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1b560 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
1b570 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
1b580 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
1b590 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b5a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b5b0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
1b5c0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
1b5d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1b5e0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
1b5f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b600 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
1b610 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
1b620 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1b630 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b640 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b650 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
1b660 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
1b670 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1b680 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b690 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b6a0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
1b6b0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
1b6c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b6d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b6e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b6f0 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
1b700 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
1b710 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b720 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1b730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b740 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
1b750 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
1b760 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1b770 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1b780 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b790 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
1b7a0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
1b7b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
1b7c0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
1b7d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b7e0 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
1b7f0 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
1b800 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
1b810 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b820 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
1b830 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  iling Functions 
1b840 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30 30  {H12280} <S60400
1b850 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
1b860 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  L.**.** These ro
1b870 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
1b880 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1b890 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
1b8a0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
1b8b0 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
1b8c0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
1b8d0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
1b8e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
1b8f0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1b900 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1b910 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
1b920 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
1b930 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
1b940 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1b950 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
1b960 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1b970 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  ]..** The callba
1b980 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54 46  ck returns a UTF
1b990 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
1b9a0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1b9b0 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65  t text.** as the
1b9c0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
1b9d0 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
1b9e0 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63  g.  Additional c
1b9f0 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a  allbacks occur.*
1ba00 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
1ba10 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
1ba20 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
1ba30 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
1ba40 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
1ba50 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
1ba60 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
1ba70 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
1ba80 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  r..**.** The cal
1ba90 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1baa0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1bab0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
1bac0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
1bad0 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
1bae0 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68  nt finishes.  Th
1baf0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1bb00 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1bb10 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1bb20 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1bb30 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1bb40 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1bb50 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1bb60 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1bb70 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 49   to run..**.** I
1bb80 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1bb90 20 7b 48 31 32 32 38 31 7d 20 54 68 65 20 63 61   {H12281} The ca
1bba0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1bbb0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b 73  registered by [s
1bbc0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
1bbd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
1bbe0 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1bbf0 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76            whenev
1bc00 65 72 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  er an SQL statem
1bc10 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
1bc20 20 74 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a   to execute and.
1bc30 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
1bc40 65 76 65 72 20 61 20 74 72 69 67 67 65 72 20 73  ever a trigger s
1bc50 75 62 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20  ubprogram first 
1bc60 62 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a  begins to run..*
1bc70 2a 0a 2a 2a 20 7b 48 31 32 32 38 32 7d 20 45 61  *.** {H12282} Ea
1bc80 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
1bc90 74 65 33 5f 74 72 61 63 65 28 29 5d 20 73 68 61  te3_trace()] sha
1bca0 6c 6c 20 6f 76 65 72 72 69 64 65 20 74 68 65 20  ll override the 
1bcb0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20  previously.**   
1bcc0 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65         registere
1bcd0 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  d trace callback
1bce0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 33 7d  ..**.** {H12283}
1bcf0 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63 61   A NULL trace ca
1bd00 6c 6c 62 61 63 6b 20 73 68 61 6c 6c 20 64 69 73  llback shall dis
1bd10 61 62 6c 65 20 74 72 61 63 69 6e 67 2e 0a 2a 2a  able tracing..**
1bd20 0a 2a 2a 20 7b 48 31 32 32 38 34 7d 20 54 68 65  .** {H12284} The
1bd30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1bd40 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
1bd50 6c 62 61 63 6b 20 73 68 61 6c 6c 20 62 65 20 61  lback shall be a
1bd60 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20   copy of.**     
1bd70 20 20 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72       the pointer
1bd80 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 33   which was the 3
1bd90 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  rd argument to [
1bda0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
1bdb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d  ..**.** {H12285}
1bdc0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1bdd0 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
1bde0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a  e callback is a.
1bdf0 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
1be00 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1be10 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  8 string contain
1be20 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ing the original
1be30 20 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20   text.**        
1be40 20 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61    of the SQL sta
1be50 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73  tement as it was
1be60 20 70 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71   passed into [sq
1be70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1be80 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
1be90 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e  or the equivalen
1bea0 74 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d  t, or an SQL com
1beb0 6d 65 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20  ment indicating 
1bec0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  the beginning.**
1bed0 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 20 74            of a t
1bee0 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
1bef0 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37  m..**.** {H12287
1bf00 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  } The callback f
1bf10 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1bf20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
1bf30 72 6f 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76  rofile()] is inv
1bf40 6f 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  oked.**         
1bf50 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
1bf60 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
1bf70 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20  .**.** {H12288} 
1bf80 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1bf90 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69  ter to the profi
1bfa0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  le callback is a
1bfb0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20   copy of.**     
1bfc0 20 20 20 20 20 74 68 65 20 33 72 64 20 70 61 72       the 3rd par
1bfd0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
1bfe0 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a  e3_profile()]..*
1bff0 2a 0a 2a 2a 20 7b 48 31 32 32 38 39 7d 20 54 68  *.** {H12289} Th
1c000 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1c010 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c  er to the profil
1c020 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a  e callback is a.
1c030 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
1c040 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1c050 38 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f  8 string that co
1c060 6e 74 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c  ntains the compl
1c070 65 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20  ete text of.**  
1c080 20 20 20 20 20 20 20 20 74 68 65 20 53 51 4c 20          the SQL 
1c090 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20  statement as it 
1c0a0 77 61 73 20 70 72 6f 63 65 73 73 65 64 20 62 79  was processed by
1c0b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c0c0 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20  e_v2()].**      
1c0d0 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76      or the equiv
1c0e0 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  alent..**.** {H1
1c0f0 32 32 39 30 7d 20 54 68 65 20 74 68 69 72 64 20  2290} The third 
1c100 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1c110 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
1c120 6b 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65  k is an estimate
1c130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
1c140 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61  the number of na
1c150 6e 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c  noseconds of wal
1c160 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71  l-clock time req
1c170 75 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  uired to.**     
1c180 20 20 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c       run the SQL
1c190 20 73 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20   statement from 
1c1a0 73 74 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e  start to finish.
1c1b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
1c1c0 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
1c1d0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
1c1e0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
1c1f0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
1c200 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
1c210 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
1c220 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
1c230 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
1c240 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
1c250 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
1c260 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
1c270 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
1c280 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c290 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
1c2a0 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32  s Callbacks {H12
1c2b0 39 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a  910} <S60400>.**
1c2c0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
1c2d0 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61   configures a ca
1c2e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1c2f0 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73  - the.** progres
1c300 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61  s callback - tha
1c310 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72  t is invoked per
1c320 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
1c330 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67   long.** running
1c340 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1c350 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
1c360 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
1c370 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1c380 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65  _table()].  An e
1c390 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
1c3a0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
1c3b0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
1c3c0 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
1c3d0 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
1c3e0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f  **.** If the pro
1c3f0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
1c400 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1c410 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
1c420 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
1c430 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
1c440 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
1c450 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
1c460 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
1c470 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
1c480 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
1c490 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
1c4a0 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
1c4b0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
1c4c0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
1c4d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1c4e0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1c4f0 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
1c500 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
1c510 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1c520 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1c530 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1c540 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1c550 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1c560 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1c570 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1c580 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1c590 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1c5a0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1c5b0 2a 0a 2a 2a 20 7b 48 31 32 39 31 31 7d 20 54 68  *.** {H12911} Th
1c5c0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1c5d0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1c5e0 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  y sqlite3_progre
1c5f0 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20  ss_handler().** 
1c600 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f           is invo
1c610 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
1c620 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
1c630 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
1c640 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c650 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
1c660 2a 20 7b 48 31 32 39 31 32 7d 20 54 68 65 20 70  * {H12912} The p
1c670 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1c680 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65   is invoked once
1c690 20 66 6f 72 20 65 76 65 72 79 20 4e 20 76 69 72   for every N vir
1c6a0 74 75 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  tual.**         
1c6b0 20 6d 61 63 68 69 6e 65 20 6f 70 63 6f 64 65 73   machine opcodes
1c6c0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1c6d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1c6e0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1c6f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  the [sqlite3_pro
1c700 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d  gress_handler()]
1c710 20 63 61 6c 6c 20 74 68 61 74 20 72 65 67 69 73   call that regis
1c720 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  tered.**        
1c730 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20    the callback. 
1c740 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   If N is less th
1c750 61 6e 20 31 2c 20 73 71 6c 69 74 65 33 5f 70 72  an 1, sqlite3_pr
1c760 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
1c770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 63 74  .**          act
1c780 73 20 61 73 20 69 66 20 61 20 4e 55 4c 4c 20 70  s as if a NULL p
1c790 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1c7a0 68 61 64 20 62 65 65 6e 20 73 70 65 63 69 66 69  had been specifi
1c7b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  ed..**.** {H1291
1c7c0 33 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  3} The progress 
1c7d0 63 61 6c 6c 62 61 63 6b 20 69 74 73 65 6c 66 20  callback itself 
1c7e0 69 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  is identified by
1c7f0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 20 20   the third.**   
1c800 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e 74 20         argument 
1c810 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  to sqlite3_progr
1c820 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 2e 0a 2a  ess_handler()..*
1c830 2a 0a 2a 2a 20 7b 48 31 32 39 31 34 7d 20 54 68  *.** {H12914} Th
1c840 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
1c850 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f  t to sqlite3_pro
1c860 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 20  gress_handler() 
1c870 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
1c880 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 70 61   void pointer pa
1c890 73 73 65 64 20 74 6f 20 74 68 65 20 70 72 6f 67  ssed to the prog
1c8a0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  ress callback.**
1c8b0 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
1c8c0 6f 6e 20 65 61 63 68 20 74 69 6d 65 20 69 74 20  on each time it 
1c8d0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
1c8e0 2a 20 7b 48 31 32 39 31 35 7d 20 49 66 20 61 20  * {H12915} If a 
1c8f0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1c900 5f 73 74 65 70 28 29 5d 20 72 65 73 75 6c 74 73  _step()] results
1c910 20 69 6e 20 66 65 77 65 72 20 74 68 61 6e 20 4e   in fewer than N
1c920 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 20 20 20 20   opcodes.**     
1c930 20 20 20 20 20 62 65 69 6e 67 20 65 78 65 63 75       being execu
1c940 74 65 64 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ted, then the pr
1c950 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1c960 69 73 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64  is never invoked
1c970 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 36 7d  ..**.** {H12916}
1c980 20 45 76 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b   Every call to [
1c990 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1c9a0 5f 68 61 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20  _handler()].**  
1c9b0 20 20 20 20 20 20 20 20 6f 76 65 72 77 72 69 74          overwrit
1c9c0 65 73 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  es any previousl
1c9d0 79 20 72 65 67 69 73 74 65 72 65 64 20 70 72 6f  y registered pro
1c9e0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1c9f0 2a 0a 2a 2a 20 7b 48 31 32 39 31 37 7d 20 49 66  *.** {H12917} If
1ca00 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1ca10 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
1ca20 73 20 4e 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70  s NULL then no p
1ca30 72 6f 67 72 65 73 73 0a 2a 2a 20 20 20 20 20 20  rogress.**      
1ca40 20 20 20 20 68 61 6e 64 6c 65 72 20 69 73 20 69      handler is i
1ca50 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nvoked..**.** {H
1ca60 31 32 39 31 38 7d 20 49 66 20 74 68 65 20 70 72  12918} If the pr
1ca70 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1ca80 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
1ca90 20 6f 74 68 65 72 20 74 68 61 6e 20 30 2c 20 74   other than 0, t
1caa0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
1cab0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
1cac0 61 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e  a if [sqlite3_in
1cad0 74 65 72 72 75 70 74 28 29 5d 20 68 61 64 20 62  terrupt()] had b
1cae0 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20  een called..**  
1caf0 20 20 20 20 20 20 20 20 3c 53 33 30 35 30 30 3e          <S30500>
1cb00 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1cb10 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1cb20 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
1cb30 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
1cb40 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1cb50 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
1cb60 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
1cb70 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37  Connection {H127
1cb80 30 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a  00} <S40200>.**.
1cb90 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1cba0 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
1cbb0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
1cbc0 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76  hose name is giv
1cbd0 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c  en by the.** fil
1cbe0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
1cbf0 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
1cc00 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
1cc10 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
1cc20 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
1cc30 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
1cc40 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
1cc50 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1cc60 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
1cc70 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
1cc80 6f 70 65 6e 31 36 28 29 2e 20 41 20 5b 64 61 74  open16(). A [dat
1cc90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cca0 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
1ccb0 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
1ccc0 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
1ccd0 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
1cce0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
1ccf0 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
1cd00 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
1cd10 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1cd20 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
1cd30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
1cd40 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
1cd50 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
1cd60 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
1cd70 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
1cd80 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1cd90 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20  ].** object. If 
1cda0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
1cdb0 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
1cdc0 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
1cdd0 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
1cde0 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
1cdf0 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
1ce00 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
1ce10 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
1ce20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1ce30 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1ce40 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1ce50 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1ce60 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1ce70 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1ce80 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1ce90 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1cea0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ..**.** The defa
1ceb0 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
1cec0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
1ced0 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
1cee0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1cef0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1cf00 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
1cf10 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
1cf20 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1cf30 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65   order if sqlite
1cf40 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73  3_open16() is us
1cf50 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
1cf60 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
1cf70 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
1cf80 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
1cf90 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
1cfa0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
1cfb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cfc0 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
1cfd0 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
1cfe0 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
1cff0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
1d000 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
1d010 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
1d020 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1d030 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
1d040 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
1d050 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
1d060 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
1d070 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
1d080 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
1d090 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
1d0a0 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
1d0b0 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
1d0c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d0d0 2e 20 20 54 68 65 20 66 6c 61 67 73 20 70 61 72  .  The flags par
1d0e0 61 6d 65 74 65 72 20 63 61 6e 20 74 61 6b 65 20  ameter can take 
1d0f0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
1d100 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
1d110 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
1d120 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
1d130 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
1d140 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20  PEN_NOMUTEX] or 
1d150 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1d160 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 3a 0a 2a  LMUTEX] flags:.*
1d170 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
1d180 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1d190 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20  ADONLY]</dt>.** 
1d1a0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1d1b0 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65   is opened in re
1d1c0 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49  ad-only mode.  I
1d1d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  f the database d
1d1e0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61  oes not.** alrea
1d1f0 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72  dy exist, an err
1d200 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
1d210 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b  /dd>.**.** <dt>[
1d220 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1d230 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
1d240 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1d250 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1d260 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1d270 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
1d280 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
1d290 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
1d2a0 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
1d2b0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
1d2c0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
1d2d0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
1d2e0 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
1d2f0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
1d300 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
1d310 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1d320 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51  d>.**.** <dt>[SQ
1d330 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1d340 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
1d350 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
1d360 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1d370 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1d380 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1d390 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
1d3a0 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20  reates it if.** 
1d3b0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
1d3c0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
1d3d0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
1d3e0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
1d3f0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
1d400 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1d410 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
1d420 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  /dd>.** </dl>.**
1d430 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1d440 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1d450 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1d460 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1d470 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1d480 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f  shown above or o
1d490 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e  ne of the combin
1d4a0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1d4b0 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77  ve combined.** w
1d4c0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
1d4d0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72  OPEN_NOMUTEX] or
1d4e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1d4f0 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 2c 0a  LLMUTEX] flags,.
1d500 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1d510 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1d520 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
1d530 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1d540 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1d550 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1d560 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1d570 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1d580 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1d590 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1d5a0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1d5b0 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1d5c0 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1d5d0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1d5e0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1d5f0 65 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53  e.  If the.** [S
1d600 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1d610 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1d620 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
1d630 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
1d640 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
1d650 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1d660 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
1d670 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
1d680 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
1d690 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
1d6a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1d6b0 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  art-time..**.** 
1d6c0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1d6d0 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1d6e0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1d6f0 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
1d700 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
1d710 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1d720 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
1d730 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
1d740 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
1d750 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
1d760 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d770 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
1d780 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1d790 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1d7a0 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
1d7b0 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
1d7c0 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
1d7d0 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
1d7e0 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
1d7f0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
1d800 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
1d810 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1d820 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
1d830 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
1d840 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
1d850 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
1d860 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
1d870 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
1d880 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
1d890 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
1d8a0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
1d8b0 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
1d8c0 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
1d8d0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1d8e0 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
1d8f0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1d900 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 70  created.  This p
1d910 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
1d920 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
1d930 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
1d940 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
1d950 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d960 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
1d970 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
1d980 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1d990 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1d9a0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1d9b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
1d9c0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
1d9d0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
1d9e0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
1d9f0 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
1da00 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1da10 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
1da20 20 75 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f   use.  If the fo
1da30 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
1da40 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1da50 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
1da60 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1da70 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
1da80 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
1da90 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
1daa0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
1dab0 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
1dac0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1dad0 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
1dae0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1daf0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
1db00 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
1db10 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
1db20 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
1db30 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
1db40 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
1db50 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
1db60 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
1db70 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
1db80 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
1db90 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
1dba0 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
1dbb0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1dbc0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
1dbd0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1dbe0 2a 0a 2a 2a 20 7b 48 31 32 37 30 31 7d 20 54 68  *.** {H12701} Th
1dbf0 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
1dc00 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1dc10 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 20  n16()], and.**  
1dc20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1dc30 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
1dc40 72 66 61 63 65 73 20 63 72 65 61 74 65 20 61 20  rfaces create a 
1dc50 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
1dc60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1dc70 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
1dc80 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20   with.**        
1dc90 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66    the database f
1dca0 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  ile given in the
1dcb0 69 72 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ir first paramet
1dcc0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30  er..**.** {H1270
1dcd0 32 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  2} The filename 
1dce0 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
1dcf0 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
1dd00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72  .**          for
1dd10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1dd20 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  ] and [sqlite3_o
1dd30 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61 73  pen_v2()] and as
1dd40 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20 20   UTF-16.**      
1dd50 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76      in the nativ
1dd60 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
1dd70 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1dd80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ()]..**.** {H127
1dd90 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  03} A successful
1dda0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1ddb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1ddc0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1ddd0 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
1dde0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
1ddf0 6e 5f 76 32 28 29 5d 20 77 72 69 74 65 73 20 61  n_v2()] writes a
1de00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
1de10 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  w.**          [d
1de20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1de30 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e 0a  on] into *ppDb..
1de40 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 34 7d 20 54  **.** {H12704} T
1de50 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1de60 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1de70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
1de80 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1de90 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
1dea0 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 5b  erfaces return [
1deb0 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e 20  SQLITE_OK] upon 
1dec0 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20 20  success,.**     
1ded0 20 20 20 20 20 6f 72 20 61 6e 20 61 70 70 72 6f       or an appro
1dee0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
1def0 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e 0a  de] on failure..
1df00 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 36 7d 20 54  **.** {H12706} T
1df10 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74 20  he default text 
1df20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e  encoding for a n
1df30 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65 61  ew database crea
1df40 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
1df50 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f        [sqlite3_o
1df60 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  pen()] or [sqlit
1df70 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 69  e3_open_v2()] wi
1df80 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a 0a  ll be UTF-8..**.
1df90 2a 2a 20 7b 48 31 32 37 30 37 7d 20 54 68 65 20  ** {H12707} The 
1dfa0 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e 63  default text enc
1dfb0 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77 20  oding for a new 
1dfc0 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65 64  database created
1dfd0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
1dfe0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
1dff0 31 36 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54  16()] will be UT
1e000 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  F-16..**.** {H12
1e010 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  709} The [sqlite
1e020 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e 74  3_open(F,D)] int
1e030 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61  erface is equiva
1e040 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  lent to.**      
1e050 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1e060 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20 77  n_v2(F,D,G,0)] w
1e070 68 65 72 65 20 74 68 65 20 47 20 70 61 72 61 6d  here the G param
1e080 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20 20  eter is.**      
1e090 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e      [SQLITE_OPEN
1e0a0 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51 4c  _READWRITE]|[SQL
1e0b0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1e0c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 31 7d  ..**.** {H12711}
1e0d0 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
1e0e0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1e0f0 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
1e100 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a  ] contains the.*
1e110 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20 76  *          bit v
1e120 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  alue [SQLITE_OPE
1e130 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65 6e  N_READONLY] then
1e140 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1e150 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20   opened.**      
1e160 20 20 20 20 66 6f 72 20 72 65 61 64 69 6e 67 20      for reading 
1e170 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  only..**.** {H12
1e180 37 31 32 7d 20 49 66 20 74 68 65 20 47 20 70 61  712} If the G pa
1e190 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1e1a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
1e1b0 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74  G,V)] contains t
1e1c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
1e1d0 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
1e1e0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1e1f0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1e200 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20  se is opened.** 
1e210 20 20 20 20 20 20 20 20 20 72 65 61 64 69 6e 67           reading
1e220 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
1e230 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f 72  possible, or for
1e240 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69 66   reading only if
1e250 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1e260 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
1e270 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
1e280 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1e290 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 33 7d  ..**.** {H12713}
1e2a0 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d 65   If the G parame
1e2b0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1e2c0 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29  open_v2(F,D,G,V)
1e2d0 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20 20  ] omits the.**  
1e2e0 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
1e2f0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
1e300 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64  REATE] and the d
1e310 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1e320 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65  .**          pre
1e330 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 61  viously exist, a
1e340 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1e350 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ned..**.** {H127
1e360 31 34 7d 20 49 66 20 74 68 65 20 47 20 70 61 72  14} If the G par
1e370 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
1e380 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1e390 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68  ,V)] contains th
1e3a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
1e3b0 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
1e3c0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64  OPEN_CREATE] and
1e3d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1e3e0 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  es not.**       
1e3f0 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78     previously ex
1e400 69 73 74 2c 20 74 68 65 6e 20 61 6e 20 61 74 74  ist, then an att
1e410 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1e420 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20 20  create and.**   
1e430 20 20 20 20 20 20 20 69 6e 69 74 69 61 6c 69 7a         initializ
1e440 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  e the database..
1e450 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 37 7d 20 49  **.** {H12717} I
1e460 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  f the filename a
1e470 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
1e480 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1e490 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
1e4a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1e4b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1e4c0 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ()] is ":memory:
1e4d0 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76 61  ", then an priva
1e4e0 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  te,.**          
1e4f0 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d 65  ephemeral, in-me
1e500 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69 73  mory database is
1e510 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
1e520 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 20   connection..** 
1e530 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49           <todo>I
1e540 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  s SQLITE_OPEN_CR
1e550 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e  EATE|SQLITE_OPEN
1e560 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75 69  _READWRITE requi
1e570 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
1e580 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  in sqlite3_open_
1e590 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  v2()?</todo>.**.
1e5a0 2a 2a 20 7b 48 31 32 37 31 39 7d 20 49 66 20 74  ** {H12719} If t
1e5b0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 4e  he filename is N
1e5c0 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
1e5d0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
1e5e0 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20  rivate,.**      
1e5f0 20 20 20 20 65 70 68 65 6d 65 72 61 6c 20 6f 6e      ephemeral on
1e600 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
1e610 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 0a  ill be created..
1e620 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64  **          <tod
1e630 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e  o>Is SQLITE_OPEN
1e640 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f  _CREATE|SQLITE_O
1e650 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65  PEN_READWRITE re
1e660 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  quired.**       
1e670 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70     in sqlite3_op
1e680 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a  en_v2()?</todo>.
1e690 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 31 7d 20 54  **.** {H12721} T
1e6a0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1e6b0 6e 65 63 74 69 6f 6e 5d 20 63 72 65 61 74 65 64  nection] created
1e6c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   by [sqlite3_ope
1e6d0 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 0a 2a  n_v2(F,D,G,V)].*
1e6e0 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
1e6f0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
1e700 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 64 65  _vfs] object ide
1e710 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 56  ntified by the V
1e720 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20 20   parameter,.**  
1e730 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 64          or the d
1e740 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1e750 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 66 20 56  vfs] object if V
1e760 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1e770 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32  er..**.** {H1272
1e780 33 7d 20 54 77 6f 20 5b 64 61 74 61 62 61 73 65  3} Two [database
1e790 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77 69   connections] wi
1e7a0 6c 6c 20 73 68 61 72 65 20 61 20 63 6f 6d 6d 6f  ll share a commo
1e7b0 6e 20 63 61 63 68 65 20 69 66 20 62 6f 74 68 20  n cache if both 
1e7c0 77 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  were.**         
1e7d0 20 6f 70 65 6e 65 64 20 77 69 74 68 20 74 68 65   opened with the
1e7e0 20 73 61 6d 65 20 56 46 53 20 77 68 69 6c 65 20   same VFS while 
1e7f0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1e800 64 65 5d 20 77 61 73 20 65 6e 61 62 6c 65 64 20  de] was enabled 
1e810 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
1e820 69 66 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d 65  if both filename
1e830 73 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  s compare equal 
1e840 75 73 69 6e 67 20 6d 65 6d 63 6d 70 28 29 20 61  using memcmp() a
1e850 66 74 65 72 20 68 61 76 69 6e 67 20 62 65 65 6e  fter having been
1e860 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 6f  .**          pro
1e870 63 65 73 73 65 64 20 62 79 20 74 68 65 20 5b 73  cessed by the [s
1e880 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 78 46 75  qlite3_vfs | xFu
1e890 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74 68  llPathname] meth
1e8a0 6f 64 20 6f 66 20 74 68 65 20 56 46 53 2e 0a 2a  od of the VFS..*
1e8b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
1e8c0 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
1e8d0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1e8e0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1e8f0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1e900 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1e910 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1e920 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1e930 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1e940 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
1e950 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
1e960 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1e970 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
1e980 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
1e990 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1e9a0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1e9b0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1e9c0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
1e9d0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
1e9e0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1e9f0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1ea00 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1ea10 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
1ea20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1ea30 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1ea40 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
1ea50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1ea60 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
1ea70 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
1ea80 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
1ea90 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
1eaa0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1eab0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
1eac0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
1ead0 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30 32 30   {H12800} <S6020
1eae0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
1eaf0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
1eb00 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1eb10 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
1eb20 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
1eb30 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1eb40 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
1eb50 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
1eb60 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
1eb70 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
1eb80 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
1eb90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1eba0 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
1ebb0 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
1ebc0 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
1ebd0 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
1ebe0 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
1ebf0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
1ec00 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1ec10 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
1ec20 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78    The sqlite3_ex
1ec30 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
1ec40 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1ec50 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
1ec60 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
1ec70 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
1ec80 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1ec90 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
1eca0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
1ecb0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
1ecc0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  sabled..**.** Th
1ecd0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
1ece0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
1ecf0 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
1ed00 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
1ed10 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
1ed20 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
1ed30 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
1ed40 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
1ed50 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d  spectively..** M
1ed60 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1ed70 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
1ed80 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
1ed90 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
1eda0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1edb0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
1edc0 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
1edd0 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
1ede0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
1edf0 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
1ee00 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
1ee10 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
1ee20 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
1ee30 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
1ee40 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
1ee50 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ace functions..*
1ee60 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
1ee70 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
1ee80 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
1ee90 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
1eea0 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
1eeb0 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
1eec0 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
1eed0 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
1eee0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
1eef0 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
1ef00 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
1ef10 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
1ef20 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
1ef30 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
1ef40 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
1ef50 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
1ef60 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
1ef70 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
1ef80 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
1ef90 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
1efa0 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
1efb0 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
1efc0 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
1efd0 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
1efe0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1eff0 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
1f000 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
1f010 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
1f020 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
1f030 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
1f040 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
1f050 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
1f060 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
1f070 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
1f080 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
1f090 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
1f0a0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
1f0b0 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
1f0c0 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
1f0d0 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
1f0e0 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
1f0f0 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
1f100 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
1f110 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
1f120 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
1f130 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
1f140 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
1f150 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
1f160 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
1f170 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
1f180 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  e set..**.** INV
1f190 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1f1a0 48 31 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c  H12801} The [sql
1f1b0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d  ite3_errcode(D)]
1f1c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1f1d0 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a  ns the numeric.*
1f1e0 2a 20 20 20 20 20 20 20 20 20 20 5b 72 65 73 75  *          [resu
1f1f0 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  lt code] or [ext
1f200 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
1f210 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
1f220 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20  recently.**     
1f230 20 20 20 20 20 66 61 69 6c 65 64 20 69 6e 74 65       failed inte
1f240 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63  rface call assoc
1f250 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
1f260 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f270 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ion] D..**.** {H
1f280 31 32 38 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  12802} The [sqli
1f290 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
1f2a0 63 6f 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61  code(D)] interfa
1f2b0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
1f2c0 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20  umeric.**       
1f2d0 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73     [extended res
1f2e0 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
1f2f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a  e most recently.
1f300 2a 2a 20 20 20 20 20 20 20 20 20 20 66 61 69 6c  **          fail
1f310 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  ed interface cal
1f320 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
1f330 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
1f340 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
1f350 2a 0a 2a 2a 20 7b 48 31 32 38 30 33 7d 20 54 68  *.** {H12803} Th
1f360 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  e [sqlite3_errms
1f370 67 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  g(D)] and [sqlit
1f380 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a  e3_errmsg16(D)].
1f390 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
1f3a0 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e  rfaces return En
1f3b0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
1f3c0 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
1f3d0 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
1f3e0 68 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20  he error in the 
1f3f0 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20  mostly recently 
1f400 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65  failed interface
1f410 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20   call,.**       
1f420 20 20 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69     encoded as ei
1f430 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
1f440 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
1f450 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37  y..**.** {H12807
1f460 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  } The strings re
1f470 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1f480 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
1f490 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1f4a0 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
1f4b0 20 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69    are valid unti
1f4c0 6c 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74  l the next SQLit
1f4d0 65 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  e interface call
1f4e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d  ..**.** {H12808}
1f4f0 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f   Calls to API ro
1f500 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e  utines that do n
1f510 6f 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ot return an err
1f520 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
1f530 20 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73      (example: [s
1f540 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
1f550 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20  t()]) do not.** 
1f560 20 20 20 20 20 20 20 20 20 63 68 61 6e 67 65 20           change 
1f570 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  the error code o
1f580 72 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e  r message return
1f590 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1f5a0 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f    [sqlite3_errco
1f5b0 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
1f5c0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1f5d0 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
1f5e0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1f5f0 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
1f600 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a  _errmsg16()]..**
1f610 0a 2a 2a 20 7b 48 31 32 38 30 39 7d 20 49 6e 74  .** {H12809} Int
1f620 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65  erfaces that are
1f630 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20   not associated 
1f640 77 69 74 68 20 61 20 73 70 65 63 69 66 69 63 0a  with a specific.
1f650 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
1f660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f670 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20  ] (examples:.** 
1f680 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1f690 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20  3_mprintf()] or 
1f6a0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
1f6b0 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a  shared_cache()].
1f6c0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e  **          do n
1f6d0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
1f6e0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1f6f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1f700 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1f710 2c 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  , [sqlite3_exten
1f720 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a  ded_errcode()],.
1f730 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1f740 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20  ite3_errmsg()], 
1f750 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
1f760 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  sg16()]..*/.int 
1f770 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1f780 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
1f790 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
1f7a0 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
1f7b0 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
1f7c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
1f7d0 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
1f7e0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
1f7f0 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
1f800 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1f810 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74  PI3REF: SQL Stat
1f820 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31  ement Object {H1
1f830 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a  3000} <H13010>.*
1f840 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
1f850 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
1f860 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1f870 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
1f880 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
1f890 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
1f8a0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
1f8b0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
1f8c0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
1f8d0 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
1f8e0 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
1f8f0 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
1f900 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
1f910 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
1f920 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
1f930 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
1f940 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
1f950 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
1f960 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
1f970 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
1f980 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
1f990 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1f9a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f9b0 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
1f9c0 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
1f9d0 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
1f9e0 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
1f9f0 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
1fa00 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1fa10 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
1fa20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
1fa30 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
1fa40 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
1fa50 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
1fa60 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
1fa70 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
1fa80 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1fa90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1faa0 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
1fab0 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
1fac0 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
1fad0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1fae0 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
1faf0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1fb00 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1fb10 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
1fb20 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
1fb30 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
1fb40 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
1fb50 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
1fb60 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1fb70 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
1fb80 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1fb90 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
1fba0 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
1fbb0 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
1fbc0 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c  imits {H12760} <
1fbd0 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20600>.**.** Th
1fbe0 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1fbf0 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
1fc00 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
1fc10 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
1fc20 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
1fc30 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
1fc40 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
1fc50 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1fc60 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
1fc70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
1fc80 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
1fc90 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
1fca0 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
1fcb0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
1fcc0 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
1fcd0 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
1fce0 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
1fcf0 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
1fd00 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
1fd10 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
1fd20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1fd30 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
1fd40 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
1fd50 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
1fd60 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64   returns the old
1fd70 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66   limit..**.** If
1fd80 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
1fd90 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
1fda0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
1fdb0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
1fdc0 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61  For the limit ca
1fdd0 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45  tegory of SQLITE
1fde0 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65  _LIMIT_XYZ there
1fdf0 20 69 73 20 61 20 68 61 72 64 20 75 70 70 65 72   is a hard upper
1fe00 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 79  .** bound set by
1fe10 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20   a compile-time 
1fe20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1fe30 61 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54  acro named SQLIT
1fe40 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54  E_MAX_XYZ..** (T
1fe50 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
1fe60 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
1fe70 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
1fe80 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20  .** Attempts to 
1fe90 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74  increase a limit
1fea0 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20   above its hard 
1feb0 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a  upper bound are.
1fec0 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e  ** silently trun
1fed0 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72  cated to the har
1fee0 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a  d upper limit..*
1fef0 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69  *.** Run time li
1ff00 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
1ff10 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
1ff20 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
1ff30 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
1ff40 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
1ff50 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
1ff60 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
1ff70 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
1ff80 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
1ff90 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1ffa0 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
1ffb0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
1ffc0 20 62 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77   be a.** webbrow
1ffd0 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
1ffe0 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
1fff0 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
20000 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
20010 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
20020 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
20030 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
20040 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
20050 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
20060 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
20070 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
20080 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
20090 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
200a0 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
200b0 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
200c0 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
200d0 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
200e0 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
200f0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
20100 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
20110 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
20120 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
20130 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
20140 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
20150 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
20160 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
20170 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
20180 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
20190 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
201a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
201b0 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
201c0 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
201d0 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
201e0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
201f0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
20200 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
20210 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
20220 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
20230 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
20240 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
20250 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
20260 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20  .**.** {H12762} 
20270 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
20280 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69  l to [sqlite3_li
20290 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72  mit(D,C,V)] wher
202a0 65 20 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  e V is.**       
202b0 20 20 20 70 6f 73 69 74 69 76 65 20 63 68 61 6e     positive chan
202c0 67 65 73 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e  ges the limit on
202d0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e   the size of con
202e0 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a  struct C in the.
202f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
20300 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20310 5d 20 44 20 74 6f 20 74 68 65 20 6c 65 73 73 65  ] D to the lesse
20320 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68  r of V and the h
20330 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 20 20 20  ard upper.**    
20340 20 20 20 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74        bound on t
20350 68 65 20 73 69 7a 65 20 6f 66 20 43 20 74 68 61  he size of C tha
20360 74 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70  t is set at comp
20370 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ile-time..**.** 
20380 7b 48 31 32 37 36 36 7d 20 41 20 73 75 63 63 65  {H12766} A succe
20390 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
203a0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43  qlite3_limit(D,C
203b0 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 20  ,V)] where V is 
203c0 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20  negative.**     
203d0 20 20 20 20 20 6c 65 61 76 65 73 20 74 68 65 20       leaves the 
203e0 73 74 61 74 65 20 6f 66 20 74 68 65 20 5b 64 61  state of the [da
203f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20400 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a  n] D unchanged..
20410 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41  **.** {H12769} A
20420 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
20430 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
20440 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72  it(D,C,V)] retur
20450 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
20460 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
20470 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a  limit on the siz
20480 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43  e of construct C
20490 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
204a0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
204b0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 69  nnection] D as i
204c0 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20 74  t was prior to t
204d0 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20  he call..*/.int 
204e0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
204f0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
20500 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
20510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
20520 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
20530 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d  egories {H12790}
20540 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59   <H12760>.** KEY
20550 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
20560 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63  tegory} {limit c
20570 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
20580 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
20590 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
205a0 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61  aspects of a [da
205b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
205c0 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  n].** that can b
205d0 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a  e limited in siz
205e0 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73  e by calls to [s
205f0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
20600 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73  .** The meanings
20610 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
20620 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f  limits are as fo
20630 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c  llows:.**.** <dl
20640 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
20650 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
20660 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
20670 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
20680 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
20690 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64  or table row.<dd
206a0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
206b0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
206c0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
206d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
206e0 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
206f0 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
20700 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
20710 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
20720 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
20730 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
20740 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
20750 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
20760 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
20770 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 6f  et of a SELECT o
20780 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
20790 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
207a0 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
207b0 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
207c0 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
207d0 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  use.</dd>.**.** 
207e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
207f0 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
20800 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
20810 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
20820 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
20830 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
20840 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
20850 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
20860 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
20870 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
20880 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
20890 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
208a0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
208b0 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
208c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
208d0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
208e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
208f0 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
20900 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
20910 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
20920 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
20930 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
20940 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
20950 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
20960 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
20970 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
20980 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
20990 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
209a0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
209b0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
209c0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
209d0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
209e0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
209f0 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 64 61  r of attached da
20a00 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a  tabases.</dd>.**
20a10 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
20a20 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
20a30 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
20a40 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20a50 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
20a60 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
20a70 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a  to the LIKE or.*
20a80 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73  * GLOB operators
20a90 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
20aa0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
20ab0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
20ac0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20ad0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
20ae0 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20  variables in an 
20af0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
20b00 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75  at can.** be bou
20b10 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c  nd.</dd>.** </dl
20b20 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
20b30 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
20b40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20b50 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
20b60 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
20b70 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
20b80 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
20b90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
20ba0 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
20bb0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
20bc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
20bd0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
20be0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
20bf0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
20c00 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
20c10 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
20c20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
20c30 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
20c40 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
20c50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
20c60 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
20c70 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
20c80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
20c90 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
20ca0 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
20cb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
20cc0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
20cd0 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
20ce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
20cf0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
20d00 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a  ER           9..
20d10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20d20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
20d30 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30   Statement {H130
20d40 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20  10} <S10000>.** 
20d50 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
20d60 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
20d70 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
20d80 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
20d90 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
20da0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
20db0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
20dc0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
20dd0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
20de0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
20df0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
20e00 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
20e10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
20e20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
20e30 2a 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f  ** prior call to
20e40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
20e50 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
20e60 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
20e70 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a  e3_open16()]..**
20e80 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
20e90 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
20ea0 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
20eb0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
20ec0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
20ed0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
20ee0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
20ef0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
20f00 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
20f10 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
20f20 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
20f30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
20f40 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
20f50 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20f60 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
20f70 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  6..**.** If the 
20f80 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
20f90 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
20fa0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
20fb0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
20fc0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
20fd0 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65  inator. If nByte
20fe0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
20ff0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
21000 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
21010 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
21020 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68  d from zSql.  Wh
21030 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
21040 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
21050 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
21060 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
21070 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
21080 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
21090 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
210a0 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
210b0 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
210c0 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
210d0 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
210e0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
210f0 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
21100 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
21110 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
21120 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
21130 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
21140 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
21150 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
21160 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
21170 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
21180 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
21190 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
211a0 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
211b0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
211c0 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20  or bytes..**.** 
211d0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
211e0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
211f0 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20  first byte past 
21200 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a  the end of the.*
21210 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  * first SQL stat
21220 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
21230 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
21240 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  nly compile the 
21250 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65  first.** stateme
21260 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
21270 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
21280 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20  ointing to what 
21290 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d  remains.** uncom
212a0 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70  piled..**.** *pp
212b0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
212c0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
212d0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
212e0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
212f0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
21300 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
21310 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65  step()].  If the
21320 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
21330 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
21340 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74  * to NULL.  If t
21350 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
21360 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
21370 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
21380 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
21390 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
213a0 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
213b0 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
213c0 7b 41 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c  {A13018} The cal
213d0 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
213e0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
213f0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
21400 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
21410 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
21420 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
21430 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
21440 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
21450 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63  t..**.** On succ
21460 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
21470 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74   is returned, ot
21480 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
21490 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
214a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
214b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
214c0 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
214d0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
214e0 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
214f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
21500 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
21510 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
21520 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
21530 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
21540 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
21550 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
21560 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
21570 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65  raged..** In the
21580 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
21590 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
215a0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
215b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
215c0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
215d0 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
215e0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
215f0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
21600 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
21610 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
21620 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
21630 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20   to.** behave a 
21640 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
21650 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  wo ways:.**.** <
21660 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49  ol>.** <li>.** I
21670 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
21680 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
21690 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
216a0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
216b0 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
216c0 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
216d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
216e0 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
216f0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
21700 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
21710 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
21720 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20  n it again.  If 
21730 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63  the schema has c
21740 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77  hanged in.** a w
21750 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  ay that makes th
21760 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c  e statement no l
21770 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71  onger valid, [sq
21780 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
21790 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75  ll still.** retu
217a0 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  rn [SQLITE_SCHEM
217b0 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20  A].  But unlike 
217c0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
217d0 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  ior, [SQLITE_SCH
217e0 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61  EMA] is.** now a
217f0 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43   fatal error.  C
21800 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
21810 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67  prepare_v2()] ag
21820 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b  ain will not mak
21830 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67  e the.** error g
21840 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75  o away.  Note: u
21850 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
21860 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
21870 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65  e text.** of the
21880 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74   parsing error t
21890 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
218a0 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
218b0 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c  ] return..** </l
218c0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
218d0 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f   When an error o
218e0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
218f0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
21900 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
21910 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
21920 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
21930 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
21940 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20  s].  The legacy 
21950 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
21960 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
21970 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
21980 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
21990 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
219a0 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
219b0 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61  and you would ha
219c0 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
219d0 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
219e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e  ite3_reset()] in
219f0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e   order.** to fin
21a00 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
21a10 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
21a20 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
21a30 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
21a40 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
21a50 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
21a60 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
21a70 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
21a80 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
21a90 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ol>.**.**
21aa0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
21ab0 2a 2a 20 7b 48 31 33 30 31 31 7d 20 54 68 65 20  ** {H13011} The 
21ac0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21ad0 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61  (db,zSql,...)] a
21ae0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
21af0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21b00 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  v2(db,zSql,...)]
21b10 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65   interfaces inte
21b20 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20  rpret the.**    
21b30 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68        text in th
21b40 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74  eir zSql paramet
21b50 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a  er as UTF-8..**.
21b60 2a 2a 20 7b 48 31 33 30 31 32 7d 20 54 68 65 20  ** {H13012} The 
21b70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21b80 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d  16(db,zSql,...)]
21b90 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
21ba0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21bb0 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e  e16_v2(db,zSql,.
21bc0 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  ..)] interfaces 
21bd0 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a  interpret the.**
21be0 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69            text i
21bf0 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72  n their zSql par
21c00 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31 36  ameter as UTF-16
21c10 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
21c20 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
21c30 20 7b 48 31 33 30 31 33 7d 20 49 66 20 74 68 65   {H13013} If the
21c40 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
21c50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
21c60 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e  are_v2(db,zSql,n
21c70 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  Byte,...)].**   
21c80 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76         and its v
21c90 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20  ariants is less 
21ca0 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53  than zero, the S
21cb0 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20  QL text is.**   
21cc0 20 20 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d         read from
21cd0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
21ce0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
21cf0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
21d00 2a 0a 2a 2a 20 7b 48 31 33 30 31 34 7d 20 49 66  *.** {H13014} If
21d10 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
21d20 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
21d30 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
21d40 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a  ql,nByte,...)].*
21d50 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69  *          and i
21d60 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e  ts variants is n
21d70 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
21d80 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73  n at most nBytes
21d90 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20   bytes of.**    
21da0 20 20 20 20 20 20 53 51 4c 20 74 65 78 74 20 69        SQL text i
21db0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
21dc0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d  ..**.** {H13015}
21dd0 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   In [sqlite3_pre
21de0 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
21df0 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64  N,P,pzTail)] and
21e00 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a   its variants.**
21e10 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65            if the
21e20 20 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78 74   zSql input text
21e30 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74   contains more t
21e40 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 74  han one SQL stat
21e50 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  ement.**        
21e60 20 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20    and pzTail is 
21e70 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a  not NULL, then *
21e80 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
21e90 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a  o point to the.*
21ea0 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74  *          first
21eb0 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65   byte past the e
21ec0 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  nd of the first 
21ed0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
21ee0 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20   zSql..**       
21ef0 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f     <todo>What do
21f00 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74  es *pzTail point
21f10 20 74 6f 20 69 66 20 74 68 65 72 65 20 69 73 20   to if there is 
21f20 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f  one statement?</
21f30 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  todo>.**.** {H13
21f40 30 31 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  016} A successfu
21f50 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
21f60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
21f70 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e  ,zSql,N,ppStmt,.
21f80 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
21f90 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
21fa0 61 72 69 61 6e 74 73 20 77 72 69 74 65 73 20 69  ariants writes i
21fb0 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f  nto *ppStmt a po
21fc0 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a  inter to a new.*
21fd0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
21fe0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21ff0 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  or a pointer to 
22000 4e 55 4c 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e  NULL if zSql con
22010 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  tains.**        
22020 20 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20    nothing other 
22030 74 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 20  than whitespace 
22040 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a  or comments..**.
22050 2a 2a 20 7b 48 31 33 30 31 39 7d 20 54 68 65 20  ** {H13019} The 
22060 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22070 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
22080 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
22090 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  s return.**     
220a0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
220b0 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61   or an appropria
220c0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
220d0 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  upon failure..**
220e0 0a 2a 2a 20 7b 48 31 33 30 32 31 7d 20 42 65 66  .** {H13021} Bef
220f0 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ore [sqlite3_pre
22100 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79  pare(db,zSql,nBy
22110 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c  te,ppStmt,pzTail
22120 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20  )] or its.**    
22130 20 20 20 20 20 20 76 61 72 69 61 6e 74 73 20 72        variants r
22140 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20  eturns an error 
22150 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72  (any value other
22160 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
22170 5d 29 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ]),.**          
22180 74 68 65 79 20 66 69 72 73 74 20 73 65 74 20 2a  they first set *
22190 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a  ppStmt to NULL..
221a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
221b0 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
221c0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
221d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
221e0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
221f0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
22200 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
22210 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
22220 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
22230 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
22240 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
22250 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
22260 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
22270 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
22280 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
22290 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
222a0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
222b0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
222c0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
222d0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
222e0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
222f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
22300 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
22310 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
22320 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
22330 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
22340 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
22350 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
22360 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
22370 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
22380 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
22390 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
223a0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
223b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
223c0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
223d0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
223e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
223f0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
22400 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
22410 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
22420 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
22430 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
22440 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
22450 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
22460 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
22470 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
22480 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
22490 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
224a0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
224b0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
224c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
224d0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
224e0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
224f0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
22500 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
22510 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
22520 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
22530 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
22540 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
22550 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
22560 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
22570 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
22580 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
22590 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
225a0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
225b0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
225c0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
225d0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
225e0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
225f0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
22600 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
22610 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
22620 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
22630 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
22640 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
22650 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
22660 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
22670 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
22680 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
22690 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
226a0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
226b0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
226c0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
226d0 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
226e0 20 53 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48   SQL {H13100} <H
226f0 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  13000>.**.** Thi
22700 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
22710 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
22720 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
22730 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
22740 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
22750 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
22760 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22770 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
22780 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
22790 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
227a0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
227b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
227c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
227d0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  2()]..**.** INVA
227e0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
227f0 31 33 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70  13101} If the [p
22800 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22810 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65  t] passed as the
22820 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
22830 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
22840 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
22850 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
22860 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
22870 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
22880 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
22890 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
228a0 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ], then [sqlite3
228b0 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a  _sql()] returns.
228c0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f  **          a po
228d0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
228e0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
228f0 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55  g containing a U
22900 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a  TF-8 rendering.*
22910 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
22920 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73  e original SQL s
22930 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
22940 7b 48 31 33 31 30 32 7d 20 49 66 20 74 68 65 20  {H13102} If the 
22950 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22960 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20 74  ent] passed as t
22970 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
22980 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
22990 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63  te3_sql()] was c
229a0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
229b0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
229c0 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20  epare()] or.**  
229d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
229e0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
229f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c  hen [sqlite3_sql
22a00 28 29 5d 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ()] returns a NU
22a10 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
22a20 2a 20 7b 48 31 33 31 30 33 7d 20 54 68 65 20 73  * {H13103} The s
22a30 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62  tring returned b
22a40 79 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53  y [sqlite3_sql(S
22a50 29 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  )] is valid unti
22a60 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  l the.**        
22a70 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
22a80 65 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65  ement] S is dele
22a90 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
22aa0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e  e3_finalize(S)].
22ab0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
22ac0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
22ad0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
22ae0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22af0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
22b00 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
22b10 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32  t {H15000} <S202
22b20 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
22b30 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
22b40 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
22b50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
22b60 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
22b70 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
22b80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
22b90 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
22ba0 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
22bb0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
22bc0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
22bd0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
22be0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
22bf0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
22c00 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c  s it stores. Val
22c10 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
22c20 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
22c30 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
22c40 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
22c50 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
22c60 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
22c70 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
22c80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
22c90 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
22ca0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
22cb0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
22cc0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
22cd0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
22ce0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
22cf0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
22d00 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
22d10 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
22d20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
22d30 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
22d40 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
22d50 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
22d60 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
22d70 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
22d80 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
22d90 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
22da0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
22db0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
22dc0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
22dd0 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
22de0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
22df0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
22e00 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
22e10 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
22e20 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75  .  A internal mu
22e30 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
22e40 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
22e50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
22e60 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
22e70 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
22e80 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
22e90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
22ea0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
22eb0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
22ec0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
22ed0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
22ee0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
22ef0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
22f00 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
22f10 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
22f20 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
22f30 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
22f40 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
22f50 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
22f60 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
22f70 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
22f80 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
22f90 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
22fa0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
22fb0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
22fc0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
22fd0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
22fe0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
22ff0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
23000 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
23010 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
23020 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
23030 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
23040 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
23050 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
23060 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
23070 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
23080 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20  between between 
23090 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
230a0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
230b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
230c0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
230d0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
230e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
230f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
23100 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
23110 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
23120 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
23130 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
23140 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
23150 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
23160 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
23170 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
23180 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
23190 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
231a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
231b0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
231c0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
231d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
231e0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
231f0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
23200 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
23210 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
23220 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
23230 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
23240 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
23250 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
23260 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
23270 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
23280 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
23290 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
232a0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
232b0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
232c0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
232d0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
232e0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
232f0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20   Context Object 
23300 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30  {H16001} <S20200
23310 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  >.**.** The cont
23320 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
23330 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
23340 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
23350 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
23360 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
23370 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61    A pointer to a
23380 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
23390 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
233a0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
233b0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
233c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
233d0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
233e0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
233f0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
23400 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
23410 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
23420 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
23430 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
23440 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
23450 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
23460 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
23470 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
23480 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
23490 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
234a0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
234b0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
234c0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
234d0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
234e0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
234f0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
23500 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
23510 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
23520 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
23530 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
23540 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
23550 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
23560 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b  red Statements {
23570 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13500} <S70300>
23580 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
23590 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
235a0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
235b0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
235c0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
235d0 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
235e0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
235f0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
23600 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49  binding}.**.** I
23610 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67  n the SQL string
23620 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  s input to [sqli
23630 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
23640 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
23650 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
23660 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
23670 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69  by a parameter i
23680 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66  n one of these f
23690 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  orms:.**.** <ul>
236a0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
236b0 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
236c0 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
236d0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
236e0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
236f0 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65  ** In the parame
23700 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20  ter forms shown 
23710 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20  above NNN is an 
23720 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
23730 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61  .** and VVV is a
23740 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20  n alpha-numeric 
23750 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20  parameter name. 
23760 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
23770 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
23780 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
23790 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
237a0 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
237b0 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
237c0 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
237d0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
237e0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
237f0 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
23800 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
23810 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
23820 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
23830 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
23840 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
23850 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
23860 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
23870 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
23880 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
23890 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
238a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
238b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
238c0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
238d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
238e0 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20   be set..** The 
238f0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
23900 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
23910 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20  dex of 1.  When 
23920 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
23930 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
23940 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
23950 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
23960 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
23970 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
23980 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
23990 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
239a0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65  currence..** The
239b0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
239c0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
239d0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
239e0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
239f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
23a00 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
23a10 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20  f desired.  The 
23a20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
23a30 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
23a40 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
23a50 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76  NN..** The NNN v
23a60 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
23a70 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
23a80 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
23a90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
23aa0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
23ab0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
23ac0 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
23ad0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  )..**.** The thi
23ae0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
23af0 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
23b00 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
23b10 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73  r..**.** In thos
23b20 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
23b30 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
23b40 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
23b50 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
23b60 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
23b70 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
23b80 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
23b90 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
23ba0 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
23bb0 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
23bc0 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
23bd0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
23be0 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  s..** If the fou
23bf0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
23c00 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c   negative, the l
23c10 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
23c20 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
23c30 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
23c40 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
23c50 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
23c60 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61  *.** The fifth a
23c70 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
23c80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
23c90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
23ca0 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
23cb0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
23cc0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
23cd0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
23ce0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
23cf0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
23d00 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
23d10 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66  shed with it. If
23d20 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
23d30 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
23d40 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
23d50 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
23d60 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
23d70 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
23d80 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
23d90 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
23da0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
23db0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
23dc0 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  reed..** If the 
23dd0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
23de0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
23df0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
23e00 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
23e10 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
23e20 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
23e30 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
23e40 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
23e50 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
23e60 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
23e70 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
23e80 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
23e90 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
23ea0 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
23eb0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
23ec0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
23ed0 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f  roes.  A zeroblo
23ee0 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
23ef0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
23f00 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
23f10 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
23f20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
23f30 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
23f40 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
23f50 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
23f60 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
23f70 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
23f80 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
23f90 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
23fa0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
23fb0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
23fc0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
23fd0 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
23fe0 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61  ** A negative va
23ff0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
24000 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
24010 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
24020 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  OB..**.** The sq
24030 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
24040 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
24050 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20  called after.** 
24060 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24070 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20  _v2()] (and its 
24080 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71  variants) or [sq
24090 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
240a0 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71  nd.** before [sq
240b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
240c0 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e  * Bindings are n
240d0 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
240e0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
240f0 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
24100 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
24110 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
24120 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
24130 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
24140 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
24150 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
24160 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20  r an error code 
24170 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67  if.** anything g
24180 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c  oes wrong.  [SQL
24190 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
241a0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
241b0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
241c0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
241d0 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  .  [SQLITE_NOMEM
241e0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
241f0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
24200 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
24210 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  SE] might be ret
24220 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72  urned if these r
24230 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
24240 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75  ed on a.** virtu
24250 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20  al machine that 
24260 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61  is the wrong sta
24270 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20  te or which has 
24280 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e  already been fin
24290 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63  alized..** Detec
242a0 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69  tion of misuse i
242b0 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41  s unreliable.  A
242c0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
242d0 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a  ld not depend.**
242e0 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   on SQLITE_MISUS
242f0 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49  E returns.  SQLI
24300 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74  TE_MISUSE is int
24310 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74  ended to indicat
24320 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65  e a.** a logic e
24330 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c  rror in the appl
24340 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65  ication.  Future
24350 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
24360 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e  ite might.** pan
24370 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72  ic rather than r
24380 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
24390 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  USE..**.** See a
243a0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
243b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
243c0 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
243d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
243e0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
243f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
24400 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
24410 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
24420 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 36  S:.**.** {H13506
24430 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65  } The [SQL state
24440 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72  ment compiler] r
24450 65 63 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73  ecognizes tokens
24460 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a   of the forms.**
24470 20 20 20 20 20 20 20 20 20 20 22 3f 22 2c 20 22            "?", "
24480 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22  ?NNN", "$VVV", "
24490 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56  :VVV", and "@VVV
244a0 22 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74  " as SQL paramet
244b0 65 72 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ers,.**         
244c0 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e   where NNN is an
244d0 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e  y sequence of on
244e0 65 20 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73  e or more digits
244f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
24500 20 77 68 65 72 65 20 56 56 56 20 69 73 20 61 6e   where VVV is an
24510 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e  y sequence of on
24520 65 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e  e or more alphan
24530 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20  umeric.**       
24540 20 20 20 63 68 61 72 61 63 74 65 72 73 20 6f 72     characters or
24550 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79   "::" optionally
24560 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 73   followed by a s
24570 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
24580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20  .**          no 
24590 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61  spaces and conta
245a0 69 6e 65 64 20 77 69 74 68 69 6e 20 70 61 72 65  ined within pare
245b0 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ntheses..**.** {
245c0 48 31 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74  H13509} The init
245d0 69 61 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  ial value of an 
245e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
245f0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   NULL..**.** {H1
24600 33 35 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20  3512} The index 
24610 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61  of an "?" SQL pa
24620 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c  rameter is one l
24630 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a  arger than the.*
24640 2a 20 20 20 20 20 20 20 20 20 20 6c 61 72 67 65  *          large
24650 73 74 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20  st index of SQL 
24660 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
24670 20 6c 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a   left, or 1 if.*
24680 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 22  *          the "
24690 3f 22 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f  ?" is the leftmo
246a0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
246b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 35 7d  ..**.** {H13515}
246c0 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
246d0 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61   "?NNN" SQL para
246e0 6d 65 74 65 72 20 69 73 20 74 68 65 20 69 6e 74  meter is the int
246f0 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20  eger NNN..**.** 
24700 7b 48 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64  {H13518} The ind
24710 65 78 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c  ex of an ":VVV",
24720 20 22 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56   "$VVV", or "@VV
24730 56 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  V" SQL parameter
24740 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
24750 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
24760 69 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73  index of leftmos
24770 74 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66  t occurrences of
24780 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
24790 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c        parameter,
247a0 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61   or one more tha
247b0 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e  n the largest in
247c0 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20  dex over all.** 
247d0 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
247e0 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20  ers to the left 
247f0 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20 66  if this is the f
24800 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a  irst occurrence.
24810 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
24820 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c 20 6f  his parameter, o
24830 72 20 31 20 69 66 20 74 68 69 73 20 69 73 20 74  r 1 if this is t
24840 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61 72 61  he leftmost para
24850 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  meter..**.** {H1
24860 33 35 32 31 7d 20 54 68 65 20 5b 53 51 4c 20 73  3521} The [SQL s
24870 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
24880 72 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  r] fails with an
24890 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a   [SQLITE_RANGE].
248a0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f  **          erro
248b0 72 20 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f  r if the index o
248c0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
248d0 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
248e0 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  1.**          or
248f0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
24900 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53  e compile-time S
24910 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42  QLITE_MAX_VARIAB
24920 4c 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20  LE_NUMBER.**    
24930 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e        parameter.
24940 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 34 7d 20  .**.** {H13524} 
24950 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
24960 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
24970 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56  lite3_bind(S,N,V
24980 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
24990 20 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65     associate the
249a0 20 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c   value V with al
249b0 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  l SQL parameters
249c0 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20   having an.**   
249d0 20 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20         index of 
249e0 4e 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  N in the [prepar
249f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
24a00 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 37 7d 20  .**.** {H13527} 
24a10 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
24a20 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
24a30 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e  lite3_bind(S,N,.
24a40 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
24a50 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20   override prior 
24a60 63 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73  calls with the s
24a70 61 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20  ame values of S 
24a80 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  and N..**.** {H1
24a90 33 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65  3530} Bindings e
24aa0 73 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73  stablished by [s
24ab0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24ac0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
24ad0 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  S,...)].**      
24ae0 20 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f      persist acro
24af0 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ss calls to [sql
24b00 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a  ite3_reset(S)]..
24b10 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 33 7d 20 49  **.** {H13533} I
24b20 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
24b30 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
24b40 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
24b50 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
24b60 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
24b70 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
24b80 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
24b90 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
24ba0 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69  ,L,D)] SQLite bi
24bb0 6e 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a  nds the first L.
24bc0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65  **          byte
24bd0 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  s of the BLOB or
24be0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
24bf0 74 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a  to by V, when L.
24c00 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e  **          is n
24c10 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
24c20 2a 2a 20 7b 48 31 33 35 33 36 7d 20 49 6e 20 63  ** {H13536} In c
24c30 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
24c40 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
24c50 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ,L,D)] or.**    
24c60 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
24c70 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
24c80 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69  ,L,D)] SQLite bi
24c90 6e 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a  nds characters.*
24ca0 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
24cb0 56 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  V through the fi
24cc0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
24cd0 65 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67  er when L is neg
24ce0 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
24cf0 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3539} In calls t
24d00 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
24d10 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
24d20 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
24d30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24d40 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
24d50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
24d60 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
24d70 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68  6(S,N,V,L,D)] wh
24d80 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63  en D is the spec
24d90 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ial.**          
24da0 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45  constant [SQLITE
24db0 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65  _STATIC], SQLite
24dc0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
24dd0 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20  e value V.**    
24de0 20 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e        is held in
24df0 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65   static unmanage
24e00 64 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c  d space that wil
24e10 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20  l not change.** 
24e20 20 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20           during 
24e30 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20  the lifetime of 
24e40 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a  the binding..**.
24e50 2a 2a 20 7b 48 31 33 35 34 32 7d 20 49 6e 20 63  ** {H13542} In c
24e60 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
24e70 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56  _bind_blob(S,N,V
24e80 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,L,D)],.**      
24e90 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
24ea0 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
24eb0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
24ec0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
24ed0 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
24ee0 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68  D)] when D is th
24ef0 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20  e special.**    
24f00 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b        constant [
24f10 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
24f20 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d  ], the routine m
24f30 61 6b 65 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  akes a.**       
24f40 20 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20     private copy 
24f50 6f 66 20 74 68 65 20 76 61 6c 75 65 20 56 20 62  of the value V b
24f60 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
24f70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 35 7d  ..**.** {H13545}
24f80 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
24f90 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
24fa0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
24fb0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
24fc0 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
24fd0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
24fe0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
24ff0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
25000 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
25010 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
25020 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75  **          a fu
25030 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69  nction, SQLite i
25040 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63  nvokes that func
25050 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20  tion to destroy 
25060 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
25070 76 61 6c 75 65 20 56 20 61 66 74 65 72 20 69 74  value V after it
25080 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
25090 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e  ing the value V.
250a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 38 7d 20  .**.** {H13548} 
250b0 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
250c0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
250d0 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65  ob(S,N,V,L)] the
250e0 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20   value bound.** 
250f0 20 20 20 20 20 20 20 20 20 69 73 20 61 20 42 4c           is a BL
25100 4f 42 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f  OB of L bytes, o
25110 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
25120 42 4c 4f 42 20 69 66 20 4c 20 69 73 20 6e 65 67  BLOB if L is neg
25130 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
25140 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3551} In calls t
25150 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
25160 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68  value(S,N,V)] th
25170 65 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79  e V argument may
25180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20  .**          be 
25190 65 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63  either a [protec
251a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
251b0 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a  e] object or an.
251c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70  **          [unp
251d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
251e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a  _value] object..
251f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
25200 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
25210 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
25220 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
25230 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
25240 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
25250 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
25260 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
25270 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
25280 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
25290 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
252a0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
252b0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
252c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
252d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
252e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
252f0 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
25300 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
25310 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
25320 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
25330 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
25340 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
25350 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
25360 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
25370 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
25380 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
25390 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
253a0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
253b0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
253c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
253d0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
253e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
253f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
25400 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
25410 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
25420 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25430 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
25440 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33   Parameters {H13
25450 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  600} <S70300>.**
25460 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
25470 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
25480 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
25490 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
254a0 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
254b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
254c0 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
254d0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
254e0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
254f0 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
25500 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
25510 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
25520 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
25530 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
25540 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
25550 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
25560 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
25570 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
25580 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   time..**.** Thi
25590 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
255a0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
255b0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
255c0 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
255d0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
255e0 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
255f0 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
25600 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
25610 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
25620 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
25630 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
25640 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
25650 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
25660 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
25670 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  n the list..**.*
25680 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
25690 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
256a0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
256b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
256c0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
256d0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
256e0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
256f0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
25700 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
25710 2a 0a 2a 2a 20 7b 48 31 33 36 30 31 7d 20 54 68  *.** {H13601} Th
25720 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
25730 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
25740 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
25750 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
25760 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e    the largest in
25770 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70  dex of all SQL p
25780 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65  arameters in the
25790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
257a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
257b0 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20 63  ] S, or 0 if S c
257c0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70  ontains no SQL p
257d0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e  arameters..*/.in
257e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
257f0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
25800 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
25810 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25820 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
25830 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30  arameter {H13620
25840 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
25850 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
25860 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
25870 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  to the name of t
25880 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20  he n-th.** [SQL 
25890 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20  parameter] in a 
258a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
258b0 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72  ent]..** SQL par
258c0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
258d0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
258e0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
258f0 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
25900 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
25910 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
25920 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
25930 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
25940 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
25950 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
25960 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
25970 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
25980 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
25990 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
259a0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a   of the name..**
259b0 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   Parameters of t
259c0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
259d0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
259e0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
259f0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
25a00 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f  also referred to
25a10 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   as "anonymous p
25a20 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
25a30 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74  * The first host
25a40 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
25a50 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
25a60 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  t 0..**.** If th
25a70 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74  e value n is out
25a80 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
25a90 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74  the n-th paramet
25aa0 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
25ab0 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
25ac0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72  returned.  The r
25ad0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
25ae0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
25af0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
25b00 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
25b10 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
25b20 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
25b30 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
25b40 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
25b50 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
25b60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25b70 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
25b80 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
25b90 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
25ba0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
25bb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
25bc0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
25bd0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
25be0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
25bf0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
25c00 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
25c10 2a 2a 20 7b 48 31 33 36 32 31 7d 20 54 68 65 20  ** {H13621} The 
25c20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
25c30 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e  rameter_name(S,N
25c40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
25c50 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
25c60 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
25c70 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f  ng of the name o
25c80 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
25c90 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  ter in.**       
25ca0 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
25cb0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
25cc0 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72  ving index N, or
25cd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c  .**          NUL
25ce0 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f  L if there is no
25cf0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77   SQL parameter w
25d00 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69  ith index N or i
25d10 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
25d20 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68    parameter with
25d30 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61   index N is an a
25d40 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
25d50 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74  er "?"..*/.const
25d60 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
25d70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
25d80 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
25d90 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
25da0 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
25db0 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
25dc0 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20  th A Given Name 
25dd0 7b 48 31 33 36 34 30 7d 20 3c 53 37 30 33 30 30  {H13640} <S70300
25de0 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  >.**.** Return t
25df0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
25e00 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
25e10 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68  en its name.  Th
25e20 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
25e30 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
25e40 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
25e50 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
25e60 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
25e70 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
25e80 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
25e90 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65   A zero.** is re
25ea0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
25eb0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
25ec0 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70  is found.  The p
25ed0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
25ee0 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
25ef0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
25f00 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
25f10 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
25f20 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
25f30 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
25f40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
25f50 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
25f60 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
25f70 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
25f80 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
25f90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
25fa0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
25fb0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
25fc0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25fd0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
25fe0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
25ff0 2a 20 7b 48 31 33 36 34 31 7d 20 54 68 65 20 5b  * {H13641} The [
26000 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
26010 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e  ameter_index(S,N
26020 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
26030 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
26040 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 53 51   the index of SQ
26050 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  L parameter in t
26060 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26070 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20  tement].**      
26080 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65      S whose name
26090 20 6d 61 74 63 68 65 73 20 74 68 65 20 55 54 46   matches the UTF
260a0 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20  -8 string N, or 
260b0 30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a  0 if there is.**
260c0 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74            no mat
260d0 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ch..*/.int sqlit
260e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
260f0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
26100 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
26110 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
26120 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
26130 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
26140 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
26150 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20  tement {H13660} 
26160 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43  <S70300>.**.** C
26170 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
26180 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
26190 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
261a0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
261b0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
261c0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
261d0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
261e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
261f0 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20  t]..** Use this 
26200 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
26210 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
26220 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  ters to NULL..**
26230 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
26240 2a 2a 0a 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54  **.** {H13661} T
26250 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  he [sqlite3_clea
26260 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69  r_bindings(S)] i
26270 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
26280 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20  all SQL.**      
26290 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 62 69      parameter bi
262a0 6e 64 69 6e 67 73 20 69 6e 20 74 68 65 20 5b 70  ndings in the [p
262b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
262c0 74 5d 20 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c  t] S back to NUL
262d0 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
262e0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
262f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
26300 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26310 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
26320 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
26330 53 65 74 20 7b 48 31 33 37 31 30 7d 20 3c 53 31  Set {H13710} <S1
26340 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  0700>.**.** Retu
26350 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
26360 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
26370 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
26380 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
26390 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
263a0 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  t]. This routine
263b0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
263c0 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
263d0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
263e0 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
263f0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
26400 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
26410 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
26420 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d  :.**.** {H13711}
26430 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
26440 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69  lumn_count(S)] i
26450 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26460 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
26470 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d  *          colum
26480 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
26490 20 73 65 74 20 67 65 6e 65 72 61 74 65 64 20 62   set generated b
264a0 79 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  y the [prepared 
264b0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a  statement] S,.**
264c0 20 20 20 20 20 20 20 20 20 20 6f 72 20 30 20 69            or 0 i
264d0 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e  f S does not gen
264e0 65 72 61 74 65 20 61 20 72 65 73 75 6c 74 20 73  erate a result s
264f0 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
26500 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
26510 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
26520 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
26530 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
26540 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
26550 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31  Set {H13720} <S1
26560 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0700>.**.** Thes
26570 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
26580 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
26590 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
265a0 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
265b0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
265c0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
265d0 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71  atement.  The sq
265e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
265f0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
26600 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
26610 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
26620 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
26630 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
26640 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
26650 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
26660 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
26670 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
26680 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  F-16 string.  Th
26690 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
266a0 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
266b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
266c0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
266d0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
266e0 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63  atement. The sec
266f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
26700 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
26710 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74  umber.  The left
26720 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
26730 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54  umber 0..**.** T
26740 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
26750 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
26760 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
26770 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
26780 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
26790 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
267a0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
267b0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  ] or until the n
267c0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
267d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
267e0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
267f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
26800 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
26810 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c  mn..**.** If sql
26820 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
26830 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
26840 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
26850 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
26860 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
26870 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
26880 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
26890 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
268a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
268b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
268c0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
268d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
268e0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
268f0 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
26900 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
26910 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
26920 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
26930 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
26940 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
26950 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
26960 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
26970 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
26980 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
26990 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
269a0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a  o the next..**.*
269b0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
269c0 0a 2a 2a 20 7b 48 31 33 37 32 31 7d 20 41 20 73  .** {H13721} A s
269d0 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
269e0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
269f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26a00 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  (S,N)].**       
26a10 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74     interface ret
26a20 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  urns the name of
26a30 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
26a40 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20  (where 0 is.**  
26a50 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74          the left
26a60 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72  most column) for
26a70 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
26a80 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
26a90 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
26aa0 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a  tement] S as a z
26ab0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
26ac0 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
26ad0 2a 2a 20 7b 48 31 33 37 32 33 7d 20 41 20 73 75  ** {H13723} A su
26ae0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
26af0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
26b00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
26b10 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  6(S,N)].**      
26b20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65      interface re
26b30 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f  turns the name o
26b40 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
26b50 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20   (where 0 is.** 
26b60 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66           the lef
26b70 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f  tmost column) fo
26b80 72 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  r the result set
26b90 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
26ba0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
26bb0 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20  atement] S as a 
26bc0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
26bd0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
26be0 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65            in the
26bf0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
26c00 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32  er..**.** {H1372
26c10 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
26c20 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61  column_name()] a
26c30 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
26c40 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20  mn_name16()].** 
26c50 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
26c60 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c  ces return a NUL
26c70 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 74 68 65  L pointer if the
26c80 79 20 61 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a  y are unable to.
26c90 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  **          allo
26ca0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
26cb0 6f 6c 64 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c  old their normal
26cc0 20 72 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e   return strings.
26cd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20  .**.** {H13725} 
26ce0 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  If the N paramet
26cf0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
26d00 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d  olumn_name(S,N)]
26d10 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
26d20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26d30 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20  name16(S,N)] is 
26d40 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
26d50 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
26d60 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
26d70 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  turn a NULL poin
26d80 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ter..**.** {H137
26d90 32 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20  26} The strings 
26da0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
26db0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26dc0 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  (S,N)] and.**   
26dd0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
26de0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
26df0 4e 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e  N)] are valid un
26e00 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20  til the next.** 
26e10 20 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f           call to
26e20 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20   either routine 
26e30 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 53 20  with the same S 
26e40 61 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73  and N parameters
26e50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
26e60 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66  until [sqlite3_f
26e70 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
26e80 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  alled..**.** {H1
26e90 33 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73  3727} When a res
26ea0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  ult column of a 
26eb0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
26ec0 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  nt contains.**  
26ed0 20 20 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c          an AS cl
26ee0 61 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f  ause, the name o
26ef0 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  f that column is
26f00 20 74 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a   the identifier.
26f10 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
26f20 68 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20  he right of the 
26f30 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63  AS keyword..*/.c
26f40 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
26f50 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
26f60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26f70 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
26f80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
26f90 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
26fa0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
26fb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26fc0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
26fd0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
26fe0 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30   {H13740} <S1070
26ff0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
27000 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
27010 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
27020 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e  mine what column
27030 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c   of what.** tabl
27040 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62  e in which datab
27050 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20  ase a result of 
27060 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
27070 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e  ment comes from.
27080 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
27090 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
270a0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
270b0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
270c0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
270d0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
270e0 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74  tring.  The _dat
270f0 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
27100 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
27110 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
27120 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
27130 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
27140 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
27150 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
27160 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
27170 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
27180 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
27190 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
271a0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
271b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
271c0 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
271d0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
271e0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
271f0 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
27200 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
27210 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
27220 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
27230 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  ng..**.** The na
27240 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
27250 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
27260 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
27270 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
27280 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
27290 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lumn..**.** The 
272a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
272b0 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  o the following 
272c0 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70  calls is a [prep
272d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
272e0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
272f0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
27300 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
27310 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
27320 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
27330 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
27340 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
27350 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
27360 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
27370 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
27380 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
27390 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
273a0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
273b0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
273c0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
273d0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
273e0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
273f0 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65  rn.** NULL.  The
27400 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
27410 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
27420 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
27430 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
27440 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72  * occurs.  Other
27450 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
27460 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
27470 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
27480 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e  ase, table.** an
27490 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  d column that qu
274a0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
274b0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
274c0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77  from..**.** As w
274d0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
274e0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
274f0 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20   postfixed with 
27500 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
27510 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
27520 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72  rings, the other
27530 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
27540 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a  n UTF-8. {END}.*
27550 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20  *.** These APIs 
27560 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
27570 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
27580 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
27590 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
275a0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
275b0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
275c0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
275d0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
275e0 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74  {A13751}.** If t
275f0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
27600 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
27610 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
27620 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
27630 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
27640 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
27650 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
27660 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
27670 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
27680 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
27690 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
276a0 0a 2a 2a 20 7b 48 31 33 37 34 31 7d 20 54 68 65  .** {H13741} The
276b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
276c0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53  _database_name(S
276d0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
276e0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
276f0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
27700 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
27710 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
27720 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68  database from wh
27730 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ich the.**      
27740 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
27750 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
27760 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27770 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64  ] S is extracted
27780 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
27790 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
277a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
277b0 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
277c0 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
277d0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
277e0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
277f0 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
27800 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
27810 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
27820 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
27830 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
27840 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
27850 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
27860 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74    the UTF-16 nat
27870 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a  ive byte order z
27880 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
27890 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
278a0 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ase.**          
278b0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e  from which the N
278c0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
278d0 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
278e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
278f0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
27900 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
27910 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
27920 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
27930 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
27940 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
27950 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
27960 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
27970 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
27980 2a 0a 2a 2a 20 7b 48 31 33 37 34 33 7d 20 54 68  *.** {H13743} Th
27990 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
279a0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e  n_table_name(S,N
279b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
279c0 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
279d0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
279e0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
279f0 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
27a00 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ble from which t
27a10 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
27a20 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
27a30 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
27a40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
27a50 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20  s extracted,.** 
27a60 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
27a70 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
27a80 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
27a90 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
27aa0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
27ab0 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
27ac0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
27ad0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
27ae0 2a 0a 2a 2a 20 7b 48 31 33 37 34 34 7d 20 54 68  *.** {H13744} Th
27af0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
27b00 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53  n_table_name16(S
27b10 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
27b20 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
27b30 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
27b40 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
27b50 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d   order zero-term
27b60 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
27b70 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  he table.**     
27b80 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20       from which 
27b90 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
27ba0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
27bb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27bc0 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ] S is.**       
27bd0 20 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72     extracted, or
27be0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
27bf0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
27c00 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
27c10 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
27c20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
27c30 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
27c40 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
27c50 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
27c60 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
27c70 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
27c80 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
27c90 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
27ca0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
27cb0 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  e UTF-8 zero-ter
27cc0 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
27cd0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
27ce0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a   from which the.
27cf0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
27d00 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
27d10 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
27d20 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65  tatement] S is e
27d30 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20  xtracted,.**    
27d40 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66        or NULL if
27d50 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
27d60 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
27d70 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  l expression.** 
27d80 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75           or if u
27d90 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
27da0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72  e memory to stor
27db0 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
27dc0 2a 20 7b 48 31 33 37 34 36 7d 20 54 68 65 20 5b  * {H13746} The [
27dd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
27de0 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e  rigin_name16(S,N
27df0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
27e00 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
27e10 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
27e20 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
27e30 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  rder zero-termin
27e40 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
27e50 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20   table.**       
27e60 20 20 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77     column from w
27e70 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73  hich the Nth res
27e80 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
27e90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
27ea0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27eb0 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65  t] S is extracte
27ec0 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
27ed0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  e Nth column.** 
27ee0 20 20 20 20 20 20 20 20 20 6f 66 20 53 20 69 73           of S is
27ef0 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65   a general expre
27f00 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62  ssion or if unab
27f10 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
27f20 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
27f30 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e    to store the n
27f40 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ame..**.** {H137
27f50 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  48} The return v
27f60 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20  alues from.**   
27f70 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
27f80 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
27f90 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
27fa0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
27fb0 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  s].**          a
27fc0 72 65 20 76 61 6c 69 64 20 66 6f 72 20 74 68 65  re valid for the
27fd0 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65   lifetime of the
27fe0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27ff0 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
28000 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65    or until the e
28010 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67  ncoding is chang
28020 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65  ed by another me
28030 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20  tadata.**       
28040 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c     interface cal
28050 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70  l for the same p
28060 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28070 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  t and column..**
28080 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
28090 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20  .**.** {A13751} 
280a0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
280b0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
280c0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20  or more.**      
280d0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
280e0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
280f0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
28100 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
28110 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
28120 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
28130 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
28140 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
28150 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 20 74  **          at t
28160 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
28170 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
28180 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
28190 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
281a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
281b0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
281c0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
281d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
281e0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
281f0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
28200 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
28210 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28220 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
28230 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28240 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
28250 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28260 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
28270 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
28280 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
28290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
282a0 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
282b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
282c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
282d0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
282e0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
282f0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
28300 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
28310 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
28320 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
28330 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e  H13760} <S10700>
28340 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
28350 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
28360 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28370 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
28380 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
28390 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
283a0 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
283b0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
283c0 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
283d0 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
283e0 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
283f0 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
28400 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
28410 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
28420 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
28430 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
28440 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
28450 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68  ned.  If the Nth
28460 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
28470 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
28480 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
28490 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
284a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
284b0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54  s returned..** T
284c0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
284d0 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
284e0 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44  -8 encoded. {END
284f0 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  }.**.** For exam
28500 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
28510 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
28520 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
28530 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
28540 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
28550 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
28560 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
28570 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
28580 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
28590 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
285a0 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
285b0 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
285c0 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
285d0 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
285e0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
285f0 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
28600 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
28610 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
28620 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  n (i==0)..**.** 
28630 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
28640 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
28650 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65  ing.  So just be
28660 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
28670 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
28680 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
28690 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
286a0 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
286b0 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
286c0 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
286d0 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
286e0 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
286f0 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
28700 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
28710 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
28720 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79   not static.  Ty
28730 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
28740 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
28750 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
28760 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
28770 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
28780 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
28790 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
287a0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36  TS:.**.** {H1376
287b0 31 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c  1}  A successful
287c0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
287d0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
287e0 65 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20  e(S,N)] returns 
287f0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 7a  a.**           z
28800 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
28810 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74  TF-8 string cont
28820 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61  aining the decla
28830 72 65 64 20 64 61 74 61 74 79 70 65 0a 2a 2a 20  red datatype.** 
28840 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
28850 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
28860 61 74 20 61 70 70 65 61 72 73 20 61 73 20 74 68  at appears as th
28870 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75  e Nth column (nu
28880 6d 62 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  mbered.**       
28890 20 20 20 20 66 72 6f 6d 20 30 29 20 6f 66 20 74      from 0) of t
288a0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f  he result set to
288b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
288c0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
288d0 2a 2a 20 7b 48 31 33 37 36 32 7d 20 20 41 20 73  ** {H13762}  A s
288e0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
288f0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
28900 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e  n_decltype16(S,N
28910 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
28920 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74  returns a zero-t
28930 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36  erminated UTF-16
28940 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
28950 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  er string.**    
28960 20 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e         containin
28970 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64  g the declared d
28980 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74  atatype of the t
28990 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
289a0 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20   appears.**     
289b0 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68        as the Nth
289c0 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65   column (numbere
289d0 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65  d from 0) of the
289e0 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74   result set to t
289f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  he.**           
28a00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28a10 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ent] S..**.** {H
28a20 31 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20  13763}  If N is 
28a30 6c 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e  less than 0 or N
28a40 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
28a50 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20   or equal to.** 
28a60 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6e 75            the nu
28a70 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
28a80 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
28a90 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a   statement] S,.*
28aa0 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  *           or i
28ab0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
28ac0 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70 72   of S is an expr
28ad0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
28ae0 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20  ry rather.**    
28af0 20 20 20 20 20 20 20 74 68 61 6e 20 61 20 74 61         than a ta
28b00 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69  ble column, or i
28b10 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
28b20 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a  ation failure.**
28b30 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
28b40 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e  s during encodin
28b50 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74  g conversions, t
28b60 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
28b70 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
28b80 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
28b90 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  pe(S,N)] or.**  
28ba0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
28bb0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
28bc0 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e  e16(S,N)] return
28bd0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   NULL..*/.const 
28be0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
28bf0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
28c00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
28c10 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
28c20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
28c30 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
28c40 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
28c50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
28c60 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
28c70 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20  tement {H13200} 
28c80 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S10000>.**.** A
28c90 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
28ca0 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
28cb0 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
28cc0 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73  ing either.** [s
28cd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28ce0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
28cf0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
28d00 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
28d10 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
28d20 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
28d30 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
28d40 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
28d50 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
28d60 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
28d70 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
28d80 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
28d90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
28da0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
28db0 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
28dc0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
28dd0 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
28de0 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
28df0 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
28e00 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
28e10 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
28e20 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
28e30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
28e40 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
28e50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28e60 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
28e70 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
28e80 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
28e90 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
28ea0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28eb0 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
28ec0 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
28ed0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
28ee0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
28ef0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
28f00 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
28f10 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
28f20 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
28f30 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
28f40 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  * In the legacy 
28f50 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
28f60 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
28f70 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
28f80 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
28f90 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
28fa0 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
28fb0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
28fc0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
28fd0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69   With the "v2" i
28fe0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
28ff0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
29000 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
29010 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
29020 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
29030 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
29040 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  l..**.** [SQLITE
29050 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
29060 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
29070 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
29080 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
29090 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
290a0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
290b0 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68   its job.  If th
290c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
290d0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
290e0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
290f0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
29100 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
29110 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
29120 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
29130 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
29140 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
29150 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
29160 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
29170 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
29180 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
29190 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
291a0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
291b0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
291c0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  *.** [SQLITE_DON
291d0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
291e0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
291f0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
29200 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
29210 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
29220 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
29230 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
29240 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
29250 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
29260 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
29270 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29280 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
29290 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
292a0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
292b0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
292c0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
292d0 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
292e0 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
292f0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
29300 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
29310 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
29320 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
29330 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
29340 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
29350 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
29360 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
29370 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
29380 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
29390 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
293a0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
293b0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
293c0 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
293d0 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
293e0 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ta..**.** [SQLIT
293f0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
29400 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
29410 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
29420 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
29430 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
29440 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
29450 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
29460 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
29470 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
29480 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
29490 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
294a0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
294b0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
294c0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
294d0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
294e0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
294f0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
29500 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
29510 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
29520 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
29530 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
29540 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
29550 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
29560 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
29570 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
29580 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
29590 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
295a0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
295b0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
295c0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
295d0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
295e0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
295f0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
29600 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
29610 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
29620 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
29630 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
29640 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
29650 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
29660 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
29670 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
29680 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
29690 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
296a0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
296b0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
296c0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
296d0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
296e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
296f0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
29700 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
29710 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
29720 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
29730 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
29740 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
29750 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
29760 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
29770 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
29780 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
29790 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
297a0 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
297b0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
297c0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
297d0 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
297e0 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
297f0 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
29800 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
29810 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
29820 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
29830 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
29840 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
29850 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
29860 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
29870 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
29880 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
29890 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
298a0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
298b0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
298c0 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
298d0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
298e0 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
298f0 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
29900 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
29910 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
29920 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
29930 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
29940 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
29950 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
29960 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
29970 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
29980 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
29990 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
299a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
299b0 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
299c0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
299d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
299e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
299f0 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
29a00 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
29a10 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
29a20 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
29a30 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
29a40 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
29a50 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
29a60 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
29a70 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
29a80 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
29a90 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
29aa0 2a 2a 20 7b 48 31 33 32 30 32 7d 20 20 49 66 20  ** {H13202}  If 
29ab0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
29ac0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65  atement] S is re
29ad0 61 64 79 20 74 6f 20 62 65 20 72 75 6e 2c 20 74  ady to be run, t
29ae0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
29af0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
29b00 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74  )] advances that
29b10 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29b20 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20  ent until.**    
29b30 20 20 20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f         completio
29b40 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73  n or until it is
29b50 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
29b60 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20   another row of 
29b70 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29b80 20 72 65 73 75 6c 74 20 73 65 74 2c 20 6f 72 20   result set, or 
29b90 75 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65  until an [sqlite
29ba0 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e  3_interrupt | in
29bb0 74 65 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20  terrupt].**     
29bc0 20 20 20 20 20 20 6f 72 20 61 20 72 75 6e 2d 74        or a run-t
29bd0 69 6d 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ime error occurs
29be0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d  ..**.** {H15304}
29bf0 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f    When a call to
29c00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
29c10 29 5d 20 63 61 75 73 65 73 20 74 68 65 20 5b 70  )] causes the [p
29c20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29c30 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  t].**           
29c40 53 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70  S to run to comp
29c50 6c 65 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63  letion, the func
29c60 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51  tion returns [SQ
29c70 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a  LITE_DONE]..**.*
29c80 2a 20 7b 48 31 35 33 30 36 7d 20 20 57 68 65 6e  * {H15306}  When
29c90 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
29ca0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74 6f  te3_step(S)] sto
29cb0 70 73 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ps because it is
29cc0 20 72 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20   ready to.**    
29cd0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e         return an
29ce0 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65  other row of the
29cf0 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74 20   result set, it 
29d00 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
29d10 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ROW]..**.** {H15
29d20 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20  308}  If a call 
29d30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
29d40 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20  (S)] encounters 
29d50 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
29d60 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
29d70 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20  pt | interrupt] 
29d80 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  or a run-time er
29d90 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ror,.**         
29da0 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20    it returns an 
29db0 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
29dc0 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e  r code that is n
29dd0 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20  ot one of.**    
29de0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
29df0 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  K], [SQLITE_ROW]
29e00 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  , or [SQLITE_DON
29e10 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31  E]..**.** {H1531
29e20 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74  0}  If an [sqlit
29e30 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
29e40 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72  nterrupt] or a r
29e50 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a  un-time error.**
29e60 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
29e70 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20  s during a call 
29e80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
29e90 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (S)].**         
29ea0 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65    for a [prepare
29eb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63  d statement] S c
29ec0 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
29ed0 20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79            legacy
29ee0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
29ef0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
29f00 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
29f10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29f20 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  16()], then the 
29f30 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
29f40 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
29f50 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
29f60 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  OR], [SQLITE_BUS
29f70 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  Y], or [SQLITE_M
29f80 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ISUSE]..*/.int s
29f90 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
29fa0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
29fb0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
29fc0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
29fd0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b  n a result set {
29fe0 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e  H13770} <S10700>
29ff0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74  .**.** Returns t
2a000 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c  he number of val
2a010 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  ues in the curre
2a020 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2a030 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  sult set..**.** 
2a040 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2a050 2a 20 7b 48 31 33 37 37 31 7d 20 20 41 66 74 65  * {H13771}  Afte
2a060 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  r a call to [sql
2a070 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68  ite3_step(S)] th
2a080 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  at returns [SQLI
2a090 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20  TE_ROW],.**     
2a0a0 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
2a0b0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29  e3_data_count(S)
2a0c0 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  ] routine will r
2a0d0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76  eturn the same v
2a0e0 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
2a0f0 20 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65    as the [sqlite
2a100 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53  3_column_count(S
2a110 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  )] function..**.
2a120 2a 2a 20 7b 48 31 33 37 37 32 7d 20 20 41 66 74  ** {H13772}  Aft
2a130 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
2a140 28 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  (S)] has returne
2a150 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  d any value othe
2a160 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  r than.**       
2a170 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d      [SQLITE_ROW]
2a180 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69   or before [sqli
2a190 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
2a1a0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
2a1b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2a1c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a1d0 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69  ment] for the fi
2a1e0 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69  rst time since i
2a1f0 74 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20  t was.**        
2a200 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
2a210 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
2a220 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2a230 74 20 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20  t | reset],.**  
2a240 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
2a250 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2a260 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  (S)] routine ret
2a270 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e  urns zero..*/.in
2a280 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
2a290 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2a2a0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2a2b0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
2a2c0 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
2a2d0 73 20 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31  s {H10265} <S101
2a2e0 31 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b  10><S10120>.** K
2a2f0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
2a300 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  TEXT.**.** {H102
2a310 36 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20  66} Every value 
2a320 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2a330 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2a340 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2a350 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2a360 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2a370 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2a380 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2a390 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2a3a0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2a3b0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2a3c0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2a3d0 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  </ul> {END}.**.*
2a3e0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2a3f0 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
2a400 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
2a410 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
2a420 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
2a430 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
2a440 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
2a450 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
2a460 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
2a470 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
2a480 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
2a490 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
2a4a0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
2a4b0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
2a4c0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2a4d0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
2a4e0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
2a4f0 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
2a500 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2a510 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
2a520 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
2a530 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2a540 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
2a550 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
2a560 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
2a570 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
2a580 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
2a590 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
2a5a0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
2a5b0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
2a5c0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
2a5d0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
2a5e0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
2a5f0 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20  es From A Query 
2a600 7b 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30  {H13800} <S10700
2a610 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
2a620 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2a630 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2a640 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
2a650 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
2a660 65 74 20 71 75 65 72 79 22 20 69 6e 74 65 72 66  et query" interf
2a670 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ace..**.** These
2a680 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2a690 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2a6a0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
2a6b0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
2a6c0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
2a6d0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20  of a query.  In 
2a6e0 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2a6f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2a700 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2a710 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a720 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2a730 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2a740 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2a750 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2a760 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2a770 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a780 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2a790 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2a7a0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2a7b0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2a7c0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2a7d0 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2a7e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2a7f0 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2a800 64 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74  d.  The leftmost
2a810 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2a820 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2a830 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a  e index 0..**.**
2a840 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
2a850 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2a860 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
2a870 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
2a880 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
2a890 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
2a8a0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
2a8b0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2a8c0 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
2a8d0 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
2a8e0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
2a8f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2a900 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2a910 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2a920 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2a930 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
2a940 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2a950 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
2a960 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
2a970 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
2a980 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
2a990 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
2a9a0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2a9b0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
2a9c0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2a9d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2a9e0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
2a9f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2aa00 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
2aa10 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
2aa20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2aa30 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
2aa40 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2aa50 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
2aa60 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2aa70 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2aa80 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2aa90 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
2aaa0 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
2aab0 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
2aac0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2aad0 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
2aae0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
2aaf0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2ab00 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
2ab10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2ab20 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
2ab30 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
2ab40 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2ab50 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
2ab60 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
2ab70 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
2ab80 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
2ab90 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
2aba0 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
2abb0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
2abc0 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
2abd0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
2abe0 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
2abf0 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
2ac00 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
2ac10 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2ac20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2ac30 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
2ac40 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
2ac50 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
2ac60 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
2ac70 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
2ac80 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
2ac90 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
2aca0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
2acb0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2acc0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
2acd0 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
2ace0 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
2acf0 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
2ad00 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2ad10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ad20 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
2ad30 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
2ad40 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rsion..**.** If 
2ad50 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2ad60 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2ad70 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2ad80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ad90 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2ada0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2adb0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2adc0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2add0 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  ng..** If the re
2ade0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
2adf0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2ae00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ae10 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
2ae20 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2ae30 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
2ae40 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2ae50 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66   of bytes..** If
2ae60 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2ae70 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2ae80 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2ae90 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
2aea0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2aeb0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2aec0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2aed0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
2aee0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2aef0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2af00 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2af10 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  g..** The value 
2af20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
2af30 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
2af40 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74  ro terminator at
2af50 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
2af60 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20  he string.  For 
2af70 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
2af80 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74  ue returned is t
2af90 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
2afa0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2afb0 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
2afc0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2afd0 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73  s..**.** Strings
2afe0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2aff0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2b000 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2b010 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2b020 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2b030 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2b040 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65  s zero terminate
2b050 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a  d.  The return.*
2b060 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
2b070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2b080 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
2b090 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20  ngth BLOB is an 
2b0a0 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69  arbitrary.** poi
2b0b0 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65  nter, possibly e
2b0c0 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ven a NULL point
2b0d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
2b0e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2b0f0 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69  es16() routine i
2b100 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c  s similar to sql
2b110 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b120 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65  s().** but leave
2b130 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20  s the result in 
2b140 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
2b150 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74   byte order inst
2b160 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a  ead of UTF-8..**
2b170 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   The zero termin
2b180 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c  ator is not incl
2b190 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75  uded in this cou
2b1a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62  nt..**.** The ob
2b1b0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2b1c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2b1d0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
2b1e0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2b1f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2b200 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
2b210 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b220 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
2b230 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2b240 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
2b250 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
2b260 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2b270 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
2b280 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
2b290 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2b2a0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2b2b0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2b2c0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2b2d0 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
2b2e0 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
2b2f0 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
2b300 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
2b310 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2b320 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2b330 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
2b340 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
2b350 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
2b360 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2b370 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2b380 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2b390 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
2b3a0 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
2b3b0 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
2b3c0 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
2b3d0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
2b3e0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
2b3f0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
2b400 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
2b410 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
2b420 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2b430 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
2b440 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
2b450 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
2b460 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2b470 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
2b480 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
2b490 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
2b4a0 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
2b4b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2b4c0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2b4d0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2b4e0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
2b4f0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
2b500 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
2b510 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
2b520 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
2b530 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
2b540 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
2b550 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
2b560 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2b570 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2b580 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
2b590 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2b5a0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2b5b0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2b5c0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2b5d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2b5e0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2b5f0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2b600 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2b610 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2b620 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
2b630 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2b640 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
2b650 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2b660 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2b670 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2b680 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2b690 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
2b6a0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2b6b0 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
2b6c0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
2b6d0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
2b6e0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2b6f0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2b700 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2b710 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
2b720 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2b730 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2b740 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2b750 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2b760 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
2b770 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2b780 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2b790 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
2b7a0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
2b7b0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2b7c0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2b7d0 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
2b7e0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2b7f0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2b800 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
2b810 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2b820 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2b830 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
2b840 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
2b850 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
2b860 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
2b870 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
2b880 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
2b890 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2b8a0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2b8b0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
2b8c0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
2b8d0 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
2b8e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
2b8f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
2b900 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
2b910 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
2b920 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2b930 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
2b940 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
2b950 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
2b960 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
2b970 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
2b980 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
2b990 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
2b9a0 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
2b9b0 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
2b9c0 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
2b9d0 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
2b9e0 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
2b9f0 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
2ba00 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
2ba10 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
2ba20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
2ba30 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
2ba40 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
2ba50 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
2ba60 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
2ba70 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
2ba80 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
2ba90 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
2baa0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
2bab0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
2bac0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2bad0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
2bae0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
2baf0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
2bb00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2bb10 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
2bb20 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
2bb30 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
2bb40 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
2bb50 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
2bb60 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
2bb70 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
2bb80 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
2bb90 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2bba0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
2bbb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2bbc0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
2bbd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bbe0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2bbf0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
2bc00 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
2bc10 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
2bc20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
2bc30 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
2bc40 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2bc50 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
2bc60 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2bc70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2bc80 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2bc90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2bca0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2bcb0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
2bcc0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
2bcd0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
2bce0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2bcf0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2bd00 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
2bd10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2bd20 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
2bd30 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2bd40 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
2bd50 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2bd60 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2bd70 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2bd80 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
2bd90 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e   </ul>.**.** Con
2bda0 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2bdb0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2bdc0 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2bdd0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2bde0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2bdf0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2be00 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2be10 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2be20 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2be30 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2be40 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70   prior pointer p
2be50 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61  oints to will ha
2be60 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
2be70 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
2be80 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
2be90 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
2bea0 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
2beb0 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
2bec0 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
2bed0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
2bee0 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
2bef0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
2bf00 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
2bf10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
2bf20 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
2bf30 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
2bf40 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
2bf50 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2bf60 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
2bf70 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
2bf80 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
2bf90 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2bfa0 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
2bfb0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2bfc0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2bfd0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2bfe0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
2bff0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
2c000 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
2c010 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
2c020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c030 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
2c040 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c050 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
2c060 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2c070 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
2c080 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
2c090 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c0a0 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
2c0b0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
2c0c0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2c0d0 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
2c0e0 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
2c0f0 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
2c100 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
2c110 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
2c120 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c130 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2c140 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c150 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
2c160 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
2c170 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
2c180 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
2c190 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2c1a0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2c1b0 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
2c1c0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2c1d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2c1e0 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
2c1f0 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
2c200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2c210 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
2c220 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
2c230 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
2c240 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20  ** The pointers 
2c250 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
2c260 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
2c270 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
2c280 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
2c290 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
2c2a0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
2c2b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2c2c0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2c2d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2c2e0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  )] is called.  T
2c2f0 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
2c300 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
2c310 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
2c320 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
2c330 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
2c340 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
2c350 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2c360 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
2c370 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
2c380 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c390 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
2c3a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
2c3b0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ree()]..**.** If
2c3c0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2c3d0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2c3e0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2c3f0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2c400 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2c410 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2c420 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2c430 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2c440 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2c450 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2c460 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2c470 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2c480 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2c490 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2c4a0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2c4b0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2c4c0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2c4d0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
2c4e0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2c4f0 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54  **.** {H13803} T
2c500 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2c510 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e  mn_blob(S,N)] in
2c520 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2c530 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c540 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
2c550 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
2c560 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2c570 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
2c580 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2c590 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
2c5a0 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e   a BLOB and then
2c5b0 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20   returns a.**   
2c5c0 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74         pointer t
2c5d0 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20  o the converted 
2c5e0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  value..**.** {H1
2c5f0 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  3806} The [sqlit
2c600 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2c610 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2c620 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
2c630 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
2c640 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 42  f bytes in the B
2c650 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65  LOB or string (e
2c660 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a  xclusive of the.
2c670 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
2c680 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74   terminator on t
2c690 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20  he string) that 
2c6a0 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  was returned by 
2c6b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c6c0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2c6d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
2c6e0 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f  umn_blob(S,N)] o
2c6f0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
2c700 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c710 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20  xt(S,N)]..**.** 
2c720 7b 48 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71  {H13809} The [sq
2c730 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c740 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  es16(S,N)] inter
2c750 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2c760 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
2c770 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2c780 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c  the string (excl
2c790 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
2c7a0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
2c7b0 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
2c7c0 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
2c7d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2c7e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
2c7f0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2c800 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c810 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a  _text16(S,N)]..*
2c820 2a 0a 2a 2a 20 7b 48 31 33 38 31 32 7d 20 54 68  *.** {H13812} Th
2c830 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2c840 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69  n_double(S,N)] i
2c850 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2c860 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c870 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
2c880 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
2c890 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2c8a0 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
2c8b0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2c8c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
2c8d0 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  o a floating poi
2c8e0 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20  nt value and.** 
2c8f0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
2c900 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
2c910 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  value..**.** {H1
2c920 33 38 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  3815} The [sqlit
2c930 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c  e3_column_int(S,
2c940 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
2c950 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2c960 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2c970 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2c980 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2c990 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
2c9a0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2c9b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c9c0 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  S into a 64-bit 
2c9d0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
2c9e0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
2c9f0 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72  eturns the lower
2ca00 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74   32 bits of that
2ca10 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
2ca20 7b 48 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71  {H13818} The [sq
2ca30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2ca40 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  64(S,N)] interfa
2ca50 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2ca60 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
2ca70 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
2ca80 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2ca90 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20   result set for 
2caa0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2cab0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cac0 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34  ent] S into a 64
2cad0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2cae0 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
2caf0 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
2cb00 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  py of that integ
2cb10 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32  er..**.** {H1382
2cb20 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
2cb30 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29  column_text(S,N)
2cb40 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2cb50 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2cb60 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
2cb70 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
2cb80 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2cb90 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
2cba0 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72       the [prepar
2cbb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2cbc0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2cbd0 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
2cbe0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2cbf0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2cc00 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2cc10 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ring..**.** {H13
2cc20 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  824} The [sqlite
2cc30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2cc40 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2cc50 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2cc60 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
2cc70 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2cc80 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2cc90 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65  sult set for the
2cca0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2ccb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ccc0 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  ] S into a zero-
2ccd0 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74  terminated 2-byt
2cce0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  e.**          al
2ccf0 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74  igned UTF-16 nat
2cd00 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73  ive byte order s
2cd10 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2cd20 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  s.**          a 
2cd30 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2cd40 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
2cd50 31 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  13827} The [sqli
2cd60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2cd70 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2cd80 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
2cd90 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49      one of [SQLI
2cda0 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_NULL], [SQLIT
2cdb0 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
2cdc0 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20  ITE_FLOAT],.**  
2cdd0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2cde0 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  TEXT], or [SQLIT
2cdf0 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
2ce00 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20  priate for.**   
2ce10 20 20 20 20 20 20 20 74 68 65 20 4e 74 68 20 63         the Nth c
2ce20 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
2ce30 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2ce40 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
2ce50 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
2ce60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ce70 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  nt] S..**.** {H1
2ce80 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74  3830} The [sqlit
2ce90 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2cea0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2ceb0 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20  returns a.**    
2cec0 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f        pointer to
2ced0 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
2cee0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2cef0 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65 0a 2a  object for the.*
2cf00 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
2cf10 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
2cf20 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2cf30 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
2cf40 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
2cf50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cf60 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  nt] S..*/.const 
2cf70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2cf80 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
2cf90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2cfa0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2cfb0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
2cfc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2cfd0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2cfe0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2cff0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2d000 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
2d010 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
2d020 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
2d030 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2d040 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2d050 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2d060 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d070 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
2d080 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
2d090 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2d0a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d0b0 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
2d0c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2d0d0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
2d0e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d0f0 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
2d100 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d110 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2d120 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2d130 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2d140 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2d150 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d160 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
2d170 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d180 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2d190 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2d1a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d1b0 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
2d1c0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2d1d0 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53  ject {H13300} <S
2d1e0 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a  70300><S30100>.*
2d1f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2d200 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
2d210 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2d220 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
2d230 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2d240 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74 65  .** If the state
2d250 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65  ment was execute
2d260 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f  d successfully o
2d270 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61  r not executed a
2d280 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53  t all, then.** S
2d290 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
2d2a0 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74 69  rned. If executi
2d2b0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
2d2c0 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20  ent failed then 
2d2d0 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
2d2e0 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
2d2f0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2d300 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
2d310 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
2d320 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2d330 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68   point during th
2d340 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  e execution of t
2d350 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2d360 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20  statement].  If 
2d370 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68  the virtual mach
2d380 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63  ine has not.** c
2d390 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
2d3a0 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  on when this rou
2d3b0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20  tine is called, 
2d3c0 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20  that is like.** 
2d3d0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20  encountering an 
2d3e0 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c  error or an [sql
2d3f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
2d400 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20   interrupt]..** 
2d410 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74  Incomplete updat
2d420 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64  es may be rolled
2d430 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61   back and transa
2d440 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c  ctions canceled,
2d450 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  .** depending on
2d460 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63   the circumstanc
2d470 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b  es, and the.** [
2d480 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75  error code] retu
2d490 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51  rned will be [SQ
2d4a0 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a  LITE_ABORT]..**.
2d4b0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2d4c0 2a 0a 2a 2a 20 7b 48 31 31 33 30 32 7d 20 54 68  *.** {H11302} Th
2d4d0 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  e [sqlite3_final
2d4e0 69 7a 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63  ize(S)] interfac
2d4f0 65 20 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a  e destroys the.*
2d500 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2d510 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d520 53 20 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61  S and releases a
2d530 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ll.**          m
2d540 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72  emory and file r
2d550 65 73 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79  esources held by
2d560 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a   that object..**
2d570 0a 2a 2a 20 7b 48 31 31 33 30 34 7d 20 49 66 20  .** {H11304} If 
2d580 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2d590 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2d5a0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
2d5b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2d5c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d5d0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e  t] S returned an
2d5e0 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20   error,.**      
2d5f0 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
2d600 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72  3_finalize(S)] r
2d610 65 74 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65  eturns that same
2d620 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73   error..*/.int s
2d630 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d640 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2d650 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2d660 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
2d670 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2d680 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33 30  t Object {H13330
2d690 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
2d6a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2d6b0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
2d6c0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
2d6d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2d6e0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2d6f0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
2d700 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
2d710 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
2d720 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c  uted..** Any SQL
2d730 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
2d740 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
2d750 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
2d760 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
2d770 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2d780 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2d790 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
2d7a0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
2d7b0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
2d7c0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
2d7d0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
2d7e0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b  indings..**.** {
2d7f0 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c  H11332} The [sql
2d800 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2d810 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
2d820 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2d830 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20  atement] S.**   
2d840 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74         back to t
2d850 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
2d860 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
2d870 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20 74  ** {H11334} If t
2d880 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2d890 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2d8a0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2d8b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2d8c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d8d0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
2d8e0 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
2d8f0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20  LITE_DONE],.**  
2d900 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73          or if [s
2d910 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2d920 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
2d930 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
2d940 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  S,.**          t
2d950 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
2d960 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
2d970 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
2d980 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74 68  * {H11336} If th
2d990 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2d9a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2d9b0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2d9c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
2d9d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d9e0 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
2d9f0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20  error, then.**  
2da00 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2da10 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
2da20 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
2da30 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
2da40 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54  **.** {H11338} T
2da50 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2da60 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2da70 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
2da80 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20  the values.**   
2da90 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73         of any [s
2daa0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2dab0 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
2dac0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2dad0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
2dae0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
2daf0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2db00 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2db10 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
2db20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
2db30 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20  ctions {H16100} 
2db40 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S20200>.** KEYW
2db50 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
2db60 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2db70 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
2db80 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2db90 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2dba0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
2dbb0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2dbc0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2dbd0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2dbe0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  two functions (c
2dbf0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
2dc00 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
2dc10 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2dc20 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
2dc30 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
2dc40 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2dc50 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
2dc60 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2dc70 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
2dc80 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2dc90 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
2dca0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62  nly difference b
2dcb0 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77  etween the.** tw
2dcc0 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65  o is that the se
2dcd0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20  cond parameter, 
2dce0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2dcf0 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f  (scalar) functio
2dd00 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2dd10 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e  e, is encoded in
2dd20 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74   UTF-8 for sqlit
2dd30 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2dd40 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a  on() and UTF-16.
2dd50 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
2dd60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2dd70 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ()..**.** The fi
2dd80 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2dd90 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2dda0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
2ddb0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
2ddc0 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
2ddd0 20 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69   added.  If a si
2dde0 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65  ngle program use
2ddf0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
2de00 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2de10 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c  ection internall
2de20 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63  y, then SQL func
2de30 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
2de40 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ded individually
2de50 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61   to.** each data
2de60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
2de70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
2de80 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2de90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
2dea0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
2deb0 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
2dec0 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20  redefined.  The 
2ded0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
2dee0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
2def0 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c   255 bytes, excl
2df00 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20  usive of.** the 
2df10 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
2df20 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
2df30 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69  name length limi
2df40 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e  t is in bytes, n
2df50 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  ot.** characters
2df60 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  .  Any attempt t
2df70 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
2df80 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
2df90 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
2dfa0 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
2dfb0 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65  _ERROR] being re
2dfc0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
2dfd0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2dfe0 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
2dff0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2e000 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
2e010 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2e020 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
2e030 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61  es. If this para
2e040 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
2e050 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  e, then the SQL 
2e060 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2e070 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
2e080 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
2e090 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
2e0a0 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
2e0b0 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
2e0c0 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
2e0d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
2e0e0 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
2e0f0 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
2e100 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
2e110 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
2e120 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74  .  Any SQL funct
2e130 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2e140 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c  on should be abl
2e150 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72  e to work.** wor
2e160 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  k with UTF-8, UT
2e170 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
2e180 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
2e190 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
2e1a0 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
2e1b0 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
2e1c0 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
2e1d0 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 61  nother.  It is a
2e1e0 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  llowed to.** inv
2e1f0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
2e200 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
2e210 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2e220 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
2e230 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
2e240 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
2e250 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
2e260 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
2e270 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
2e280 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
2e290 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2e2a0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2e2b0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
2e2c0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
2e2d0 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
2e2e0 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
2e2f0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
2e300 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
2e310 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
2e320 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
2e330 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
2e340 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
2e350 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
2e360 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
2e370 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2e380 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
2e390 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
2e3a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
2e3b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
2e3c0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
2e3d0 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
2e3e0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
2e3f0 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
2e400 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
2e410 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
2e420 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2e430 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  ata()]..**.** Th
2e440 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74  e seventh, eight
2e450 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61  h and ninth para
2e460 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
2e470 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
2e480 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
2e490 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
2e4a0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
2e4b0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
2e4c0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2e4d0 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c  ggregate. A scal
2e4e0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
2e4f0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2e500 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2e510 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
2e520 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70  ack only, NULL p
2e530 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62  ointers should b
2e540 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2e550 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2e560 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
2e570 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
2e580 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2e590 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2e5a0 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
2e5b0 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
2e5c0 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70  NULL should be p
2e5d0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
2e5e0 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78   To delete an ex
2e5f0 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
2e600 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2e610 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66  ate, pass NULL f
2e620 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
2e630 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e  ction callbacks.
2e640 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72  .**.** It is per
2e650 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
2e660 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
2e670 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2e680 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
2e690 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
2e6a0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
2e6b0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
2e6c0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
2e6d0 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
2e6e0 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
2e6f0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
2e700 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73    SQLite will us
2e710 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
2e720 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f  ntation most clo
2e730 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
2e740 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
2e750 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
2e760 6e 20 69 73 20 75 73 65 64 2e 20 20 41 20 66 75  n is used.  A fu
2e770 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2e780 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
2e790 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
2e7a0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
2e7b0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
2e7c0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
2e7d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2e7e0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
2e7f0 6e 41 72 67 2e 20 20 41 20 66 75 6e 63 74 69 6f  nArg.  A functio
2e800 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
2e810 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2e820 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
2e830 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
2e840 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
2e850 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
2e860 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2e870 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
2e880 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
2e890 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
2e8a0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
2e8b0 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
2e8c0 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
2e8d0 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
2e8e0 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
2e8f0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
2e900 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2e910 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
2e920 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
2e930 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 42  d UTF16..**.** B
2e940 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
2e950 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
2e960 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
2e970 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2e980 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65  unctions..** The
2e990 20 66 69 72 73 74 20 61 70 70 6c 69 63 61 74 69   first applicati
2e9a0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2e9b0 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e  ion with a given
2e9c0 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20   name overrides 
2e9d0 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20  all.** built-in 
2e9e0 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65  functions in the
2e9f0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
2ea00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68  connection] with
2ea10 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a   the same name..
2ea20 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 70  ** Subsequent ap
2ea30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2ea40 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74  d functions of t
2ea50 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c  he same name onl
2ea60 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70  y override .** p
2ea70 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  rior application
2ea80 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2ea90 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 65  ns that are an e
2eaa0 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74  xact match for t
2eab0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2eac0 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70  parameters and p
2ead0 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e  referred encodin
2eae0 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70 6c  g..**.** An appl
2eaf0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2eb00 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
2eb10 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
2eb20 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
2eb30 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
2eb40 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
2eb50 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
2eb60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2eb70 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
2eb80 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
2eb90 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
2eba0 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
2ebb0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
2ebc0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
2ebd0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2ebe0 2a 2a 20 7b 48 31 36 31 30 33 7d 20 54 68 65 20  ** {H16103} The 
2ebf0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ec00 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c 58 2c 2e  function16(D,X,.
2ec10 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  ..)] interface s
2ec20 68 61 6c 6c 20 62 65 68 61 76 65 0a 2a 2a 20 20  hall behave.**  
2ec30 20 20 20 20 20 20 20 20 61 73 20 5b 73 71 6c 69          as [sqli
2ec40 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ec50 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e  ion(D,X,...)] in
2ec60 20 65 76 65 72 79 20 77 61 79 20 65 78 63 65 70   every way excep
2ec70 74 20 74 68 61 74 20 69 74 0a 2a 2a 20 20 20 20  t that it.**    
2ec80 20 20 20 20 20 20 69 6e 74 65 72 70 72 65 74 73        interprets
2ec90 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20   the X argument 
2eca0 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  as zero-terminat
2ecb0 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20  ed UTF-16.**    
2ecc0 20 20 20 20 20 20 6e 61 74 69 76 65 20 62 79 74        native byt
2ecd0 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20  e order instead 
2ece0 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69  of as zero-termi
2ecf0 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a  nated UTF-8..**.
2ed00 2a 2a 20 7b 48 31 36 31 30 36 7d 20 41 20 73 75  ** {H16106} A su
2ed10 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
2ed20 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ion of the.**   
2ed30 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2ed40 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2ed50 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e  D,X,N,E,...)] in
2ed60 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65  terface shall re
2ed70 67 69 73 74 65 72 0a 2a 2a 20 20 20 20 20 20 20  gister.**       
2ed80 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63     or replaces c
2ed90 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2eda0 73 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61  s in the [databa
2edb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2edc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65  .**          use
2edd0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  d to implement t
2ede0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2edf0 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70  named X with N p
2ee00 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20  arameters.**    
2ee10 20 20 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67        and having
2ee20 20 61 20 70 72 65 66 65 72 72 65 64 20 74 65 78   a preferred tex
2ee30 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e  t encoding of E.
2ee40 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 39 7d 20  .**.** {H16109} 
2ee50 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
2ee60 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  l to [sqlite3_cr
2ee70 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2ee80 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a  X,N,E,P,F,S,L)].
2ee90 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
2eea0 6c 20 72 65 70 6c 61 63 65 20 74 68 65 20 50 2c  l replace the P,
2eeb0 20 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c   F, S, and L val
2eec0 75 65 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69  ues from any pri
2eed0 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a  or calls with.**
2eee0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
2eef0 6d 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20  me D, X, N, and 
2ef00 45 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20  E values..**.** 
2ef10 7b 48 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71  {H16112} The [sq
2ef20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ef30 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20  ction(D,X,...)] 
2ef40 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2ef50 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  fail.**         
2ef60 20 69 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   if the SQL func
2ef70 74 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a  tion name X is.*
2ef80 2a 20 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65  *          longe
2ef90 72 20 74 68 61 6e 20 32 35 35 20 62 79 74 65 73  r than 255 bytes
2efa0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
2efb0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
2efc0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 38  r..**.** {H16118
2efd0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2efe0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2eff0 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d  ,X,N,E,P,F,S,L)]
2f000 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20   interface.**   
2f010 20 20 20 20 20 20 20 73 68 61 6c 6c 20 66 61 69         shall fai
2f020 6c 20 75 6e 6c 65 73 73 20 65 69 74 68 65 72 20  l unless either 
2f030 46 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 53 20  F is NULL and S 
2f040 61 6e 64 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55  and L are non-NU
2f050 4c 4c 20 6f 72 0a 2a 2a 2a 20 20 20 20 20 20 20  LL or.***       
2f060 20 20 46 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20    F is non-NULL 
2f070 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20  and S and L are 
2f080 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  NULL..**.** {H16
2f090 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  121} The [sqlite
2f0a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f0b0 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  n(D,...)] interf
2f0c0 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c 73 20  ace shall fails 
2f0d0 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
2f0e0 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f      error code o
2f0f0 66 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  f [SQLITE_BUSY] 
2f100 69 66 20 74 68 65 72 65 20 65 78 69 73 74 20 5b  if there exist [
2f110 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f120 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  nts].**         
2f130 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2f140 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2f150 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
2f160 0a 2a 2a 20 7b 48 31 36 31 32 34 7d 20 54 68 65  .** {H16124} The
2f170 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f180 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2f190 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
2f1a0 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 0a  shall fail with.
2f1b0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20 65  **          an e
2f1c0 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
2f1d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70  LITE_ERROR] if p
2f1e0 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 6c 65  arameter N is le
2f1f0 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ss.**          t
2f200 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
2f210 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a  r than 127..**.*
2f220 2a 20 7b 48 31 36 31 32 37 7d 20 57 68 65 6e 20  * {H16127} When 
2f230 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
2f240 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  e, the [sqlite3_
2f250 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2f260 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  D,X,N,...)].**  
2f270 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
2f280 65 20 73 68 61 6c 6c 20 72 65 67 69 73 74 65 72  e shall register
2f290 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65   callbacks to be
2f2a0 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65   invoked for the
2f2b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
2f2c0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2f2d0 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 68        named X wh
2f2e0 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  en the number of
2f2f0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
2f300 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2f310 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
2f320 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  actly N..**.** {
2f330 48 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20 69  H16130} When N i
2f340 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69 74  s -1, the [sqlit
2f350 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f360 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a  on(D,X,N,...)].*
2f370 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
2f380 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67 69 73  face shall regis
2f390 74 65 72 20 63 61 6c 6c 62 61 63 6b 73 20 74 6f  ter callbacks to
2f3a0 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   be invoked for 
2f3b0 74 68 65 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20  the SQL.**      
2f3c0 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d      function nam
2f3d0 65 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e 75  ed X with any nu
2f3e0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2f3f0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 33  s..**.** {H16133
2f400 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  } When calls to 
2f410 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f420 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
2f430 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
2f440 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70 6c   specify multipl
2f450 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f460 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2f470 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20 20  nction X.**     
2f480 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f 6e       and when on
2f490 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f4a0 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74 68   has N>=0 and th
2f4b0 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28 2d  e other has N=(-
2f4c0 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  1).**          t
2f4d0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2f4e0 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  n with a non-zer
2f4f0 6f 20 4e 20 73 68 61 6c 6c 20 62 65 20 70 72 65  o N shall be pre
2f500 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ferred..**.** {H
2f510 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c  16136} When call
2f520 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  s to [sqlite3_cr
2f530 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2f540 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  X,N,E,...)].**  
2f550 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79 20          specify 
2f560 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2f570 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2f580 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20  same function X 
2f590 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
2f5a0 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72   the same number
2f5b0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20   of arguments N 
2f5c0 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
2f5d0 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  nt.**          e
2f5e0 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e  ncodings E, then
2f5f0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2f600 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63  ion where E matc
2f610 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  hes the.**      
2f620 20 20 20 20 64 61 74 61 62 61 73 65 20 65 6e 63      database enc
2f630 6f 64 69 6e 67 20 73 68 61 6c 6c 20 70 72 65 66  oding shall pref
2f640 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  erred..**.** {H1
2f650 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67  6139} For an agg
2f660 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2f670 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e  ion created usin
2f680 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
2f690 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f6a0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
2f6b0 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e  ,0,S,L)] the fin
2f6c0 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20  alizer.**       
2f6d0 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 73 68     function L sh
2f6e0 61 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e  all always be in
2f6f0 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  voked exactly on
2f700 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  ce if the.**    
2f710 20 20 20 20 20 20 73 74 65 70 20 66 75 6e 63 74        step funct
2f720 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20  ion S is called 
2f730 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
2f740 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34 32  s..**.** {H16142
2f750 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  } When SQLite in
2f760 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68 65  vokes either the
2f770 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20   xFunc or xStep 
2f780 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20  function of.**  
2f790 20 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69          an appli
2f7a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2f7b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
2f7c0 67 67 72 65 67 61 74 65 20 63 72 65 61 74 65 64  ggregate created
2f7d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
2f7e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f7f0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b  function()] or [
2f800 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f810 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a  unction16()],.**
2f820 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
2f830 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c  he array of [sql
2f840 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2f850 63 74 73 20 70 61 73 73 65 64 20 61 73 20 74 68  cts passed as th
2f860 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
2f870 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 68  ird parameter sh
2f880 61 6c 6c 20 62 65 20 5b 70 72 6f 74 65 63 74 65  all be [protecte
2f890 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2f8a0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74   objects..*/.int
2f8b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2f8c0 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
2f8d0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2f8e0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2f8f0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2f900 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2f910 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2f920 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2f930 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f940 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2f950 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2f960 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2f970 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2f980 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2f990 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2f9a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2f9b0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2f9c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2f9d0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2f9e0 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
2f9f0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2fa00 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2fa10 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2fa20 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2fa30 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2fa40 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2fa50 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2fa60 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2fa70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fa80 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2fa90 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2faa0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2fab0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a  context*).);../*
2fac0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2fad0 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31  xt Encodings {H1
2fae0 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c  0267} <S50200> <
2faf0 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H16100>.**.** Th
2fb00 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
2fb10 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
2fb20 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
2fb30 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
2fb40 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
2fb50 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
2fb60 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
2fb70 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
2fb80 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
2fb90 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
2fba0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
2fbb0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
2fbc0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
2fbd0 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
2fbe0 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
2fbf0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2fc00 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
2fc10 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
2fc20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
2fc30 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2fc40 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
2fc50 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2fc60 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
2fc70 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2fc80 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
2fc90 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
2fca0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
2fcb0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
2fcc0 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
2fcd0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
2fce0 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
2fcf0 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
2fd00 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
2fd10 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
2fd20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
2fd30 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2fd40 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
2fd50 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
2fd60 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
2fd70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2fd80 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
2fd90 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
2fda0 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
2fdb0 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
2fdc0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
2fdd0 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
2fde0 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
2fdf0 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
2fe00 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
2fe10 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
2fe20 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
2fe30 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2fe40 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
2fe50 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
2fe60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2fe70 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2fe80 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
2fe90 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
2fea0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
2feb0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2fec0 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
2fed0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2fee0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
2fef0 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
2ff00 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2ff10 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
2ff20 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
2ff30 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
2ff40 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
2ff50 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
2ff60 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2ff70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
2ff80 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
2ff90 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
2ffa0 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a  int64,int),void*
2ffb0 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
2ffc0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
2ffd0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
2ffe0 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
2fff0 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
30000 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30   {H15100} <S2020
30010 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  0>.**.** The C-l
30020 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
30030 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
30040 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
30050 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
30060 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
30070 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
30080 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
30090 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
300a0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
300b0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
300c0 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
300d0 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
300e0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
300f0 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
30100 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
30110 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
30120 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
30130 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
30140 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
30150 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
30160 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
30170 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30180 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
30190 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61  s..** The 4th pa
301a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
301b0 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
301c0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
301d0 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
301e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
301f0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
30200 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
30210 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30220 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
30230 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
30240 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
30250 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
30260 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
30270 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
30280 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30290 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
302a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
302b0 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
302c0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
302d0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
302e0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
302f0 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
30300 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
30310 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
30320 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
30330 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
30340 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
30350 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  r..**.** These r
30360 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
30370 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
30380 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
30390 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
303a0 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
303b0 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
303c0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
303d0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
303e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
303f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
30400 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
30410 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
30420 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
30430 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
30440 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30450 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
30460 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
30470 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
30480 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
30490 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
304a0 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
304b0 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ne.  The.** sqli
304c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
304d0 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
304e0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
304f0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
30500 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
30510 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
30520 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
30530 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
30540 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
30550 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
30560 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
30570 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
30580 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
30590 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
305a0 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
305b0 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
305c0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
305d0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
305e0 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
305f0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
30600 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
30610 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
30620 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
30630 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
30640 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
30650 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
30660 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
30670 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
30680 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
30690 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
306a0 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
306b0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
306c0 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
306d0 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
306e0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
306f0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
30700 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
30710 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  rned..**.** Plea
30720 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
30730 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
30740 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
30750 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
30760 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
30770 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
30780 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
30790 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
307a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
307b0 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
307c0 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
307d0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
307e0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
307f0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
30800 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
30810 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
30820 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
30830 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
30840 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
30850 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
30860 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
30870 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
30880 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
30890 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
308a0 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
308b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
308c0 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
308d0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
308e0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30  TS:.**.** {H1510
308f0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
30900 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69  value_blob(V)] i
30910 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
30920 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
30930 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
30940 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30950 63 74 20 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42  ct V into a BLOB
30960 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20   and then.**    
30970 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
30980 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
30990 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a  onverted value..
309a0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54  **.** {H15106} T
309b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
309c0 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e 74 65  e_bytes(V)] inte
309d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
309e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
309f0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
30a00 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
30a10 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
30a20 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
30a30 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
30a40 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
30a50 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
30a60 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
30a70 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
30a80 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
30a90 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29  e3_value_blob(V)
30aa0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
30ab0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30ac0 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20  text(V)]..**.** 
30ad0 7b 48 31 35 31 30 39 7d 20 54 68 65 20 5b 73 71  {H15109} The [sq
30ae0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
30af0 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63  s16(V)] interfac
30b00 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
30b10 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
30b20 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
30b30 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
30b40 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
30b50 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
30b60 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
30b70 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
30b80 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
30b90 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
30ba0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
30bb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30bc0 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20  t16(V)],.**     
30bd0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61       [sqlite3_va
30be0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d  lue_text16be(V)]
30bf0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  , or [sqlite3_va
30c00 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d  lue_text16le(V)]
30c10 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d  ..**.** {H15112}
30c20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
30c30 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69  lue_double(V)] i
30c40 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
30c50 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
30c60 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
30c70 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30c80 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61  ct V into a floa
30c90 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
30ca0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
30cb0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
30cc0 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a  of that value..*
30cd0 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d 20 54 68  *.** {H15115} Th
30ce0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
30cf0 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66 61  _int(V)] interfa
30d00 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
30d10 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
30d20 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30d30 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
30d40 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
30d50 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
30d60 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
30d70 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32  rns the lower 32
30d80 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e   bits of that in
30d90 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  teger..**.** {H1
30da0 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  5118} The [sqlit
30db0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 56  e3_value_int64(V
30dc0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
30dd0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
30de0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
30df0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
30e00 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
30e10 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
30e20 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
30e30 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
30e40 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74  copy of that int
30e50 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  eger..**.** {H15
30e60 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  121} The [sqlite
30e70 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d  3_value_text(V)]
30e80 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
30e90 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
30ea0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
30eb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30ec0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
30ed0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
30ee0 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F-8.**          
30ef0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
30f00 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
30f10 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
30f20 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54 68 65 20  ** {H15124} The 
30f30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30f40 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65 72 66  ext16(V)] interf
30f50 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
30f60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
30f70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30f80 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
30f90 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
30fa0 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
30fb0 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
30fc0 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
30fd0 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
30fe0 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
30ff0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
31000 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
31010 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32  ng..**.** {H1512
31020 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
31030 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56  value_text16be(V
31040 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
31050 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
31060 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
31070 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
31080 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
31090 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
310a0 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
310b0 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
310c0 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20  6 big-endian.** 
310d0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
310e0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
310f0 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
31100 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
31110 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  130} The [sqlite
31120 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
31130 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
31140 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
31150 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
31160 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31170 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
31180 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
31190 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
311a0 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
311b0 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
311c0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
311d0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
311e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
311f0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
31200 20 7b 48 31 35 31 33 33 7d 20 54 68 65 20 5b 73   {H15133} The [s
31210 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
31220 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
31230 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
31240 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49      one of [SQLI
31250 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_NULL], [SQLIT
31260 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
31270 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20  ITE_FLOAT],.**  
31280 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
31290 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  TEXT], or [SQLIT
312a0 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
312b0 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20  priate for.**   
312c0 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
312d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
312e0 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  t V..**.** {H151
312f0 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
31300 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
31310 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ype(V)] interfac
31320 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20  e converts.**   
31330 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74         the [prot
31340 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
31350 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
31360 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69 6e 74  to either an int
31370 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20  eger or.**      
31380 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67 20 70      a floating p
31390 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20 69 74  oint value if it
313a0 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f   can do so witho
313b0 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20  ut loss of.**   
313c0 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69         informati
313d0 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  on, and returns 
313e0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
313f0 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ULL],.**        
31400 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45    [SQLITE_INTEGE
31410 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
31420 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
31430 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
31440 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20    [SQLITE_BLOB] 
31450 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
31460 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
31470 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
31480 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
31490 65 63 74 20 56 20 61 66 74 65 72 20 74 68 65 20  ect V after the 
314a0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74 65 6d  conversion attem
314b0 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  pt..*/.const voi
314c0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
314d0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
314e0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
314f0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
31500 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31510 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
31520 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
31530 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
31540 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
31550 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
31560 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
31570 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
31580 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
31590 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
315a0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
315b0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
315c0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
315d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
315e0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
315f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
31600 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
31610 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
31620 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
31630 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31640 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
31650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
31660 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
31670 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
31680 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
31690 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
316a0 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
316b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
316c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
316d0 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
316e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
316f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
31700 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
31710 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
31720 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30  {H16210} <S20200
31730 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  >.**.** The impl
31740 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
31750 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
31760 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
31770 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
31780 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
31790 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
317a0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
317b0 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
317c0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
317d0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
317e0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
317f0 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69  d for a.** parti
31800 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
31810 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65   SQLite allocate
31820 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f  s nBytes of memo
31830 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
31840 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61  hat.** memory, a
31850 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
31860 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73  nter to it. On s
31870 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
31880 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
31890 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
318a0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
318b0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
318c0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
318d0 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ex,.** the same 
318e0 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
318f0 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ed. The implemen
31900 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67  tation of the ag
31910 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a  gregate can use.
31920 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  ** the returned 
31930 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
31940 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
31950 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
31960 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
31970 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72  allocated buffer
31980 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
31990 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e  ate.** query con
319a0 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
319b0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
319c0 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f  r should be a co
319d0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
319e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
319f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
31a00 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
31a10 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
31a20 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
31a30 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
31a40 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
31a50 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
31a60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
31a70 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
31a80 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
31a90 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
31aa0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
31ab0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
31ac0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
31ad0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
31ae0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20  .**.** {H16211} 
31af0 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61  The first invoca
31b00 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
31b10 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31b20 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20  xt(C,N)] for.** 
31b30 20 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69           a parti
31b40 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f  cular instance o
31b50 66 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66  f an aggregate f
31b60 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70  unction (for a p
31b70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20  articular.**    
31b80 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29        context C)
31b90 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
31ba0 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74  o allocate N byt
31bb0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  es of memory,.**
31bc0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
31bd0 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
31be0 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
31bf0 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   to the allocate
31c00 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  d memory..**.** 
31c10 7b 48 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65  {H16213} If a me
31c20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
31c30 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
31c40 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
31c50 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
31c60 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
31c70 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
31c80 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  on returns 0..**
31c90 0a 2a 2a 20 7b 48 31 36 32 31 35 7d 20 53 65 63  .** {H16215} Sec
31ca0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
31cb0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
31cc0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
31cd0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
31ce0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66  _context(C,N)] f
31cf0 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74  or the same cont
31d00 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a  ext pointer C.**
31d10 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65            ignore
31d20 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
31d30 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
31d40 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d  inter to the sam
31d50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c  e.**          bl
31d60 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65  ock of memory re
31d70 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69  turned by the fi
31d80 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  rst invocation..
31d90 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54  **.** {H16217} T
31da0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
31db0 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
31dc0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31dd0 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20  t(C,N)] is.**   
31de0 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63         automatic
31df0 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68  ally freed on th
31e00 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b  e next call to [
31e10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
31e20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
31e30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31e40 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72  e()] for the [pr
31e50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31e60 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20  ] containing.** 
31e70 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67           the agg
31e80 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
31e90 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
31ea0 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f  context C..*/.vo
31eb0 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
31ec0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
31ed0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
31ee0 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
31ef0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
31f00 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
31f10 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c  tions {H16240} <
31f20 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
31f30 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
31f40 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
31f50 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
31f60 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
31f70 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
31f80 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
31f90 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
31fa0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
31fb0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31fc0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
31fd0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
31fe0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
31ff0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
32000 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
32010 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
32020 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
32030 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
32040 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
32050 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
32060 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
32070 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
32080 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
32090 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
320a0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
320b0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
320c0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d  :.**.** {H16243}
320d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73   The [sqlite3_us
320e0 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65  er_data(C)] inte
320f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
32100 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
32110 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65          P pointe
32120 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  r from the [sqli
32130 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32140 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
32150 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
32160 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72    or [sqlite3_cr
32170 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
32180 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
32190 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20  ] call that.**  
321a0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
321b0 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ed the SQL funct
321c0 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
321d0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ith [sqlite3_con
321e0 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64  text] C..*/.void
321f0 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
32200 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
32210 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
32220 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
32230 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
32240 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35  Functions {H1625
32250 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32  0} <S60600><S202
32260 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
32270 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
32280 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
32290 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
322a0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
322b0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
322c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
322d0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
322e0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
322f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32300 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
32310 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
32320 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
32330 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
32340 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
32350 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
32360 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
32370 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
32380 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
32390 2a 20 7b 48 31 36 32 35 33 7d 20 54 68 65 20 5b  * {H16253} The [
323a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
323b0 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e  db_handle(C)] in
323c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
323d0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
323e0 20 20 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e            D poin
323f0 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ter from the [sq
32400 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32410 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
32420 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
32430 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
32440 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
32450 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  6(D,X,N,E,P,F,S,
32460 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a  L)] call that.**
32470 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
32480 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e  ered the SQL fun
32490 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64  ction associated
324a0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63   with [sqlite3_c
324b0 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71  ontext] C..*/.sq
324c0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
324d0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
324e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
324f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
32500 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
32510 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31  xiliary Data {H1
32520 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6270} <S20200>.*
32530 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
32540 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
32550 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
32560 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
32570 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
32580 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
32590 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
325a0 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
325b0 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
325c0 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
325d0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
325e0 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
325f0 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
32600 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
32610 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
32620 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
32630 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
32640 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
32650 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
32660 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
32670 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
32680 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
32690 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
326a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
326b0 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
326c0 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
326d0 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
326e0 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
326f0 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
32700 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
32710 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
32720 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
32730 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
32740 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
32750 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
32760 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
32770 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
32780 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
32790 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
327a0 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
327b0 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
327c0 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
327d0 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
327e0 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
327f0 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ocation..**.** T
32800 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
32810 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
32820 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
32830 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
32840 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
32850 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
32860 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
32870 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
32880 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
32890 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
328a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
328b0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20  ed function. If 
328c0 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
328d0 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
328e0 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
328f0 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
32900 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
32910 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
32920 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
32930 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
32940 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
32950 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
32960 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
32970 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
32980 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
32990 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
329a0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
329b0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
329c0 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
329d0 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
329e0 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
329f0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
32a00 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
32a10 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
32a20 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
32a30 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32a40 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
32a50 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
32a60 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
32a70 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
32a80 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
32a90 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
32aa0 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
32ab0 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55   If it is not NU
32ac0 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
32ad0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
32ae0 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
32af0 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
32b00 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
32b10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32b20 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
32b30 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
32b40 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
32b50 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
32b60 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
32b70 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
32b80 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
32b90 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
32ba0 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
32bb0 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
32bc0 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
32bd0 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
32be0 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
32bf0 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
32c00 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
32c10 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e  ny time.  The on
32c20 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
32c30 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
32c40 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
32c50 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
32c60 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
32c70 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70  pped..**.** In p
32c80 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
32c90 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
32ca0 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
32cb0 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
32cc0 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
32cd0 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
32ce0 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
32cf0 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
32d00 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
32d10 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a  SQL variables..*
32d20 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
32d30 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
32d40 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
32d50 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
32d60 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
32d70 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
32d80 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
32d90 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32  S:.**.** {H16272
32da0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
32db0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d  et_auxdata(C,N)]
32dc0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
32dd0 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
32de0 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61           to meta
32df0 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
32e00 77 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72  with the Nth par
32e10 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51  ameter of the SQ
32e20 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
32e30 20 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e         whose con
32e40 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55  text is C, or NU
32e50 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e  LL if there is n
32e60 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  o metadata assoc
32e70 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  iated.**        
32e80 20 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61    with that para
32e90 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  meter..**.** {H1
32ea0 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6274} The [sqlit
32eb0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
32ec0 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,N,P,D)] interfa
32ed0 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74  ce assigns a met
32ee0 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20  adata.**        
32ef0 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74    pointer P to t
32f00 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72  he Nth parameter
32f10 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
32f20 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78  tion with contex
32f30 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  t C..**.** {H162
32f40 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  76} SQLite will 
32f50 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
32f60 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73  uctor D with a s
32f70 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ingle argument.*
32f80 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68  *          which
32f90 20 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   is the metadata
32fa0 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f   pointer P follo
32fb0 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  wing a call to.*
32fc0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
32fd0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
32fe0 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53  C,N,P,D)] when S
32ff0 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20  QLite ceases to 
33000 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  hold.**         
33010 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a   the metadata..*
33020 2a 0a 2a 2a 20 7b 48 31 36 32 37 37 7d 20 53 51  *.** {H16277} SQ
33030 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68  Lite ceases to h
33040 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72  old metadata for
33050 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
33060 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
33070 20 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20         when the 
33080 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61  value of that pa
33090 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e  rameter changes.
330a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20  .**.** {H16278} 
330b0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65  When [sqlite3_se
330c0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
330d0 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  D)] is invoked, 
330e0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
330f0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61  *          is ca
33100 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69  lled for any pri
33110 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  or metadata asso
33120 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
33130 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
33140 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
33150 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65  t C and paramete
33160 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  r N..**.** {H162
33170 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  79} SQLite will 
33180 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73  call destructors
33190 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74   for any metadat
331a0 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a  a it is holding.
331b0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61  **          in a
331c0 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65   particular [pre
331d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
331e0 20 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a   S when either.*
331f0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
33200 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72  te3_reset(S)] or
33210 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
33220 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
33230 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
33240 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
33250 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33260 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
33270 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33280 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
33290 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
332a0 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
332b0 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
332c0 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
332d0 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
332e0 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
332f0 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c 53  vior {H10280} <S
33300 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30100>.**.** The
33310 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
33320 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
33330 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
33340 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
33350 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
33360 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
33370 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
33380 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49  sult_blob()].  I
33390 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
333a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
333b0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
333c0 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
333d0 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
333e0 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
333f0 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
33400 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
33410 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
33420 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a  estroyed.  The.*
33430 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
33440 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
33450 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
33460 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
33470 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
33480 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
33490 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
334a0 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
334b0 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
334c0 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
334d0 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
334e0 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
334f0 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
33500 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
33510 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
33520 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
33530 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
33540 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  191..*/.typedef 
33550 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
33560 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
33570 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
33580 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
33590 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
335a0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
335b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
335c0 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
335d0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
335e0 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
335f0 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
33600 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
33610 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  An SQL Function 
33620 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32 30 30  {H16400} <S20200
33630 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
33640 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
33650 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
33660 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
33670 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
33680 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
33690 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
336a0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
336b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
336c0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
336d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
336e0 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
336f0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
33700 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
33710 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
33720 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
33730 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
33740 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
33750 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
33760 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
33770 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
33780 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
33790 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
337a0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
337b0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
337c0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
337d0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
337e0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
337f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33800 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
33810 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
33820 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
33830 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33840 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
33850 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
33860 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
33870 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
33880 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
33890 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
338a0 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
338b0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
338c0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
338d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
338e0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
338f0 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
33900 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
33910 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33920 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
33930 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
33940 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
33950 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
33960 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
33970 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
33980 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
33990 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
339a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
339b0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
339c0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
339d0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
339e0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
339f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
33a00 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
33a10 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
33a20 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
33a30 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
33a40 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
33a50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
33a60 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
33a70 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
33a80 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
33a90 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
33aa0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
33ab0 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
33ac0 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  on..** SQLite us
33ad0 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
33ae0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
33af0 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
33b00 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
33b10 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
33b20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33b30 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
33b40 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
33b50 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69  r message.  SQLi
33b60 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
33b70 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
33b80 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
33b90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33ba0 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
33bb0 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
33bc0 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
33bd0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
33be0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
33bf0 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
33c00 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
33c10 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70    If the third p
33c20 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
33c30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33c40 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
33c50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33c60 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
33c70 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
33c80 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
33c90 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
33ca0 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
33cb0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
33cc0 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cter..** If the 
33cd0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
33ce0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
33cf0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
33d00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33d10 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
33d20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
33d30 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
33d40 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
33d50 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
33d60 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
33d70 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
33d80 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54  or message..** T
33d90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33da0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
33db0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33dc0 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
33dd0 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
33de0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
33df0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
33e00 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
33e10 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
33e20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
33e30 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
33e40 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
33e50 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
33e60 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
33e70 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65  out harm..** The
33e80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33e90 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
33ea0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
33eb0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
33ec0 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
33ed0 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
33ee0 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
33ef0 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65  function.  By de
33f00 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
33f10 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
33f20 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62  TE_ERROR.  A sub
33f30 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
33f40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33f50 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
33f60 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33f70 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
33f80 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
33f90 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
33fa0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
33fb0 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69  esult_toobig() i
33fc0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
33fd0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
33fe0 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
33ff0 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
34000 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
34010 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  to long to repre
34020 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  sent..**.** The 
34030 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
34040 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
34050 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
34060 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
34070 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
34080 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
34090 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
340a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
340b0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
340c0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
340d0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
340e0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
340f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34100 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
34110 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
34120 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
34130 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
34140 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
34150 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34160 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
34170 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
34180 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
34190 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
341a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
341b0 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
341c0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
341d0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
341e0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
341f0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
34200 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
34210 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
34220 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
34230 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
34240 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34250 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
34260 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
34270 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34280 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
34290 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
342a0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
342b0 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
342c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
342d0 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
342e0 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
342f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
34300 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
34310 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34320 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
34330 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
34340 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
34350 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
34360 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
34370 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
34380 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
34390 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
343a0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
343b0 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  ** SQLite takes 
343c0 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
343d0 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
343e0 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
343f0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
34400 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
34410 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
34420 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  faces..** If the
34430 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
34440 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
34450 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
34460 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
34470 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
34480 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
34490 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
344a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
344b0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
344c0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
344d0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
344e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
344f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
34500 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
34510 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
34520 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
34530 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
34540 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
34550 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
34560 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
34570 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
34580 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
34590 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
345a0 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a  nction result..*
345b0 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
345c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
345d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
345e0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
345f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
34600 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
34610 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
34620 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
34630 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
34640 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
34650 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
34660 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
34670 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
34680 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
34690 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  t result..** If 
346a0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
346b0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
346c0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
346d0 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73  terfaces or.** s
346e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
346f0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
34700 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
34710 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
34720 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
34730 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
34740 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
34750 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
34760 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
34770 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74 20 6f  ** copy the it o
34780 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
34790 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61 73 20  tor when it has 
347a0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
347b0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
347c0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
347d0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
347e0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
347f0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
34800 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34810 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
34820 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
34830 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
34840 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
34850 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
34860 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
34870 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
34880 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
34890 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
348a0 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
348b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
348c0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
348d0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
348e0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
348f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34900 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34910 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
34920 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
34930 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34940 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
34950 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
34960 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20  ameter.  The.** 
34970 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34980 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
34990 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
349a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
349b0 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
349c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
349d0 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
349e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
349f0 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
34a00 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
34a10 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
34a20 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
34a30 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
34a40 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65  ..** A [protecte
34a50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34a60 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
34a70 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
34a80 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
34a90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
34aa0 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
34ab0 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
34ac0 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
34ad0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34ae0 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
34af0 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
34b00 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
34b10 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
34b20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
34b30 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
34b40 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
34b50 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
34b60 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
34b70 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34b80 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
34b90 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
34ba0 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
34bb0 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
34bc0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
34bd0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
34be0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20  .**.** {H16403} 
34bf0 54 68 65 20 64 65 66 61 75 6c 74 20 72 65 74 75  The default retu
34c00 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  rn value from an
34c10 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
34c20 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  s NULL..**.** {H
34c30 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  16406} The [sqli
34c40 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
34c50 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
34c60 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
34c70 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
34c80 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
34c90 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 42  tion C to be a B
34ca0 4c 4f 42 20 74 68 61 74 20 69 73 20 4e 20 62 79  LOB that is N by
34cb0 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
34cc0 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69  in length and wi
34cd0 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  th content point
34ce0 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a  ed to by V..**.*
34cf0 2a 20 7b 48 31 36 34 30 39 7d 20 54 68 65 20 5b  * {H16409} The [
34d00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
34d10 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65  ouble(C,V)] inte
34d20 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
34d30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
34d40 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
34d50 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
34d60 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
34d70 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  t value V..**.**
34d80 20 7b 48 31 36 34 31 32 7d 20 54 68 65 20 5b 73   {H16412} The [s
34d90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34da0 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65  ror(C,V,N)] inte
34db0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
34dc0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
34dd0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75       value of fu
34de0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
34df0 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
34e00 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
34e10 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
34e20 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46  ERROR] and a UTF
34e30 2d 38 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  -8 error message
34e40 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75   copied from V u
34e50 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  p to the.**     
34e60 20 20 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20       first zero 
34e70 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20  byte or until N 
34e80 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20 69  bytes are read i
34e90 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e  f N is positive.
34ea0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20  .**.** {H16415} 
34eb0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
34ec0 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c  ult_error16(C,V,
34ed0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  N)] interface ch
34ee0 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
34ef0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
34f00 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
34f10 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
34f20 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
34f30 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
34f40 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61  [SQLITE_ERROR] a
34f50 6e 64 20 61 20 55 54 46 2d 31 36 20 6e 61 74 69  nd a UTF-16 nati
34f60 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 65 72  ve byte order er
34f70 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
34f80 20 20 20 20 20 20 20 20 63 6f 70 69 65 64 20 66          copied f
34f90 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20  rom V up to the 
34fa0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
34fb0 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e  nator or until N
34fc0 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20   bytes.**       
34fd0 20 20 20 61 72 65 20 72 65 61 64 20 69 66 20 4e     are read if N
34fe0 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a   is positive..**
34ff0 0a 2a 2a 20 7b 48 31 36 34 31 38 7d 20 54 68 65  .** {H16418} The
35000 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35010 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29  _error_toobig(C)
35020 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
35030 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
35040 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
35050 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
35060 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
35070 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
35080 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
35090 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47    [SQLITE_TOOBIG
350a0 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72  ] and an appropr
350b0 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
350c0 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32  ge..**.** {H1642
350d0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
350e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
350f0 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  em(C)] interface
35100 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
35110 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
35120 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
35130 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
35140 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
35150 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
35160 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e         [SQLITE_N
35170 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70  OMEM] and an app
35180 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
35190 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  essage..**.** {H
351a0 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  16424} The [sqli
351b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
351c0 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65  _code(C,E)] inte
351d0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
351e0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
351f0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
35200 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
35210 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
35220 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20  with error code 
35230 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54  E..**          T
35240 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
35250 20 74 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67   text is unchang
35260 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32  ed..**.** {H1642
35270 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
35280 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d  result_int(C,V)]
35290 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
352a0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
352b0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
352c0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
352d0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 69   be the 32-bit i
352e0 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
352f0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54  **.** {H16430} T
35300 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
35310 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69  lt_int64(C,V)] i
35320 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
35330 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
35340 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
35350 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
35360 65 20 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74  e the 64-bit int
35370 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a  eger value V..**
35380 0a 2a 2a 20 7b 48 31 36 34 33 33 7d 20 54 68 65  .** {H16433} The
35390 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
353a0 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66  _null(C)] interf
353b0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
353c0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
353d0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
353e0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c  tion C to be NUL
353f0 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36  L..**.** {H16436
35400 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
35410 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
35420 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
35430 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
35440 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
35450 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
35460 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
35470 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  8 string.**     
35480 20 20 20 20 20 56 20 75 70 20 74 6f 20 74 68 65       V up to the
35490 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
354a0 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
354b0 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
354c0 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
354d0 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
354e0 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
354f0 48 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c  H16439} The [sql
35500 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35510 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74  16(C,V,N,D)] int
35520 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
35530 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
35540 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
35550 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
35560 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
35570 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
35580 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
35590 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
355a0 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e  t zero if N is n
355b0 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
355c0 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74      or the first
355d0 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
355e0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
355f0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34  ve..**.** {H1644
35600 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
35610 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
35620 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
35630 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
35640 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
35650 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
35660 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
35670 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69   UTF-16 big-endi
35680 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
35690 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68  tring V up to th
356a0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
356b0 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
356c0 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
356d0 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
356e0 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  r V if N is non-
356f0 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
35700 7b 48 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71  {H16445} The [sq
35710 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35720 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
35730 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
35740 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
35750 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
35760 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
35770 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 6c 69  be the UTF-16 li
35780 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20  ttle-endian.**  
35790 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56          string V
357a0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
357b0 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65   zero if N is ne
357c0 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
357d0 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20     or the first 
357e0 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20  N bytes of V if 
357f0 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
35800 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38  e..**.** {H16448
35810 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
35820 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29  esult_value(C,V)
35830 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
35840 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
35850 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
35860 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
35870 6f 20 62 65 20 74 68 65 20 5b 75 6e 70 72 6f 74  o be the [unprot
35880 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
35890 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  lue].**         
358a0 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a   object V..**.**
358b0 20 7b 48 31 36 34 35 31 7d 20 54 68 65 20 5b 73   {H16451} The [s
358c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
358d0 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74  roblob(C,N)] int
358e0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
358f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
35900 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
35910 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
35920 61 6e 20 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f  an N-byte BLOB o
35930 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a  f all zeros..**.
35940 2a 2a 20 7b 48 31 36 34 35 34 7d 20 54 68 65 20  ** {H16454} The 
35950 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35960 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71  error()] and [sq
35970 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35980 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  or16()].**      
35990 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d      interfaces m
359a0 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
359b0 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67  eir error messag
359c0 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65  e strings before
359d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
359e0 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  urning..**.** {H
359f0 31 36 34 35 37 7d 20 49 66 20 74 68 65 20 44 20  16457} If the D 
35a00 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d  destructor param
35a10 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
35a20 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
35a30 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
35a40 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
35a50 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
35a60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  )], [sqlite3_res
35a70 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e  ult_text16(C,V,N
35a80 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
35a90 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
35aa0 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
35ab0 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
35ac0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
35ad0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
35ae0 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63  V,N,D)] is the c
35af0 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
35b00 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20  STATIC].**      
35b10 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74      then no dest
35b20 72 75 63 74 6f 72 20 69 73 20 65 76 65 72 20 63  ructor is ever c
35b30 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69  alled on the poi
35b40 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74  nter V and SQLit
35b50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  e.**          as
35b60 73 75 6d 65 73 20 74 68 61 74 20 56 20 69 73 20  sumes that V is 
35b70 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  immutable..**.**
35b80 20 7b 48 31 36 34 36 30 7d 20 49 66 20 74 68 65   {H16460} If the
35b90 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61   D destructor pa
35ba0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
35bb0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
35bc0 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
35bd0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
35be0 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c  result_text(C,V,
35bf0 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  N,D)], [sqlite3_
35c00 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
35c10 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
35c20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
35c30 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
35c40 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,N,D)], or.**  
35c50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
35c60 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
35c70 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68  (C,V,N,D)] is th
35c80 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20  e constant.**   
35c90 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
35ca0 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74  RANSIENT] then t
35cb0 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  he interfaces ma
35cc0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
35cd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
35ce0 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72  ntent of V and r
35cf0 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e  etains the copy.
35d00 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20  .**.** {H16463} 
35d10 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63  If the D destruc
35d20 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tor parameter to
35d30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35d40 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _blob(C,V,N,D)],
35d50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
35d60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35d70 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71  t(C,V,N,D)], [sq
35d80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35d90 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  t16(C,V,N,D)],.*
35da0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
35db0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
35dc0 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f  6be(C,V,N,D)], o
35dd0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
35de0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35df0 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
35e00 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f   is some value o
35e10 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
35e20 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61        the consta
35e30 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  nts [SQLITE_STAT
35e40 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  IC] and [SQLITE_
35e50 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a  TRANSIENT] then.
35e60 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69  **          SQLi
35e70 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
35e80 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
35e90 77 69 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e  with V as its on
35ea0 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20  ly argument.**  
35eb0 20 20 20 20 20 20 20 20 77 68 65 6e 20 69 74 20          when it 
35ec0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
35ed0 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a  h the V value..*
35ee0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
35ef0 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
35f00 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
35f10 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
35f20 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
35f30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35f40 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
35f50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
35f60 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
35f70 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
35f80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35f90 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
35fa0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
35fb0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
35fc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35fd0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
35fe0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
35ff0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
36000 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
36010 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
36020 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36030 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
36040 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
36050 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36060 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
36070 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
36080 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
36090 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
360a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
360b0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
360c0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
360d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
360e0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
360f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36100 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
36110 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
36120 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36130 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
36140 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
36150 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
36160 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
36170 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36180 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
36190 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
361a0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
361b0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
361c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
361d0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
361e0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
361f0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
36200 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
36210 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
36220 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
36230 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
36240 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
36250 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
36260 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36270 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
36280 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
36290 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
362a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
362b0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
362c0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
362d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
362e0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
362f0 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20  ating Sequences 
36300 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30  {H16600} <S20300
36310 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  >.**.** These fu
36320 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64  nctions are used
36330 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c   to add new coll
36340 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
36350 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  to the.** [datab
36360 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36370 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
36380 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
36390 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
363a0 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61  of the new colla
363b0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
363c0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20   specified as a 
363d0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
363e0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
363f0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
36400 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
36410 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
36420 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
36430 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69   string for sqli
36440 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36450 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c  tion16(). In all
36460 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61   cases.** the na
36470 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20  me is passed as 
36480 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
36490 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
364a0 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
364b0 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e  gument may be on
364c0 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
364d0 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ts [SQLITE_UTF8]
364e0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
364f0 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  16LE] or [SQLITE
36500 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63  _UTF16BE], indic
36510 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75  ating that the u
36520 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ser-supplied.** 
36530 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
36540 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69  to be passed poi
36550 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
36560 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
36570 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  TF-8,.** UTF-16 
36580 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f  little-endian, o
36590 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64  r UTF-16 big-end
365a0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
365b0 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  y. The.** third 
365c0 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61  argument might a
365d0 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55  lso be [SQLITE_U
365e0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f  TF16_ALIGNED] to
365f0 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a   indicate that.*
36600 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
36610 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
36620 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
36630 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
36640 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68   of UTF-16 in th
36650 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
36660 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
36670 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  computer..**.** 
36680 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
36690 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72   user supplied r
366a0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70  outine must be p
366b0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66  assed as the fif
366c0 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  th.** argument. 
366d0 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
366e0 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  this is the same
366f0 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65   as deleting the
36700 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
36710 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20  quence (so that 
36720 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61  SQLite cannot ca
36730 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a  ll it anymore)..
36740 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65  ** Each time the
36750 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70   application sup
36760 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  plied function i
36770 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73  s invoked, it is
36780 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74   passed.** as it
36790 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
367a0 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  r a copy of the 
367b0 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20  void* passed as 
367c0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
367d0 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
367e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
367f0 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
36800 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36810 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
36820 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65  remaining argume
36830 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69  nts to the appli
36840 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20  cation-supplied 
36850 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20  routine are two 
36860 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68  strings,.** each
36870 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
36880 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29  a (length, data)
36890 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65   pair and encode
368a0 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  d in the encodin
368b0 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61  g.** that was pa
368c0 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
368d0 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20  d argument when 
368e0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  the collation se
368f0 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65  quence was.** re
36900 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20  gistered. {END} 
36910 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
36920 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69   defined collati
36930 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  on routine shoul
36940 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61  d.** return nega
36950 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
36960 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69  sitive if the fi
36970 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
36980 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61  ss than,.** equa
36990 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
369a0 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
369b0 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53   string. i.e. (S
369c0 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32  TRING1 - STRING2
369d0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
369e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
369f0 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
36a00 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
36a10 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
36a20 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
36a30 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72  it takes an extr
36a40 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  a argument which
36a50 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
36a60 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c   for.** the coll
36a70 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74  ation.  The dest
36a80 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
36a90 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
36aa0 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f  ion is.** destro
36ab0 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65  yed and is passe
36ac0 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
36ad0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
36ae0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a   void* pointer.*
36af0 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
36b00 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36b10 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61  n_v2()..** Colla
36b20 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f  tions are destro
36b30 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  yed when they ar
36b40 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
36b50 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74  later calls to t
36b60 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20  he.** collation 
36b70 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
36b80 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b  ns or when the [
36b90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36ba0 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a  ion] is closed.*
36bb0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
36bc0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
36bd0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
36be0 2a 2a 20 7b 48 31 36 36 30 33 7d 20 41 20 73 75  ** {H16603} A su
36bf0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
36c00 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
36c10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36c20 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
36c30 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65  X,E,P,F,D)] inte
36c40 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  rface.**        
36c50 20 20 72 65 67 69 73 74 65 72 73 20 66 75 6e 63    registers func
36c60 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f  tion F as the co
36c70 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
36c80 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  n used to.**    
36c90 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20        implement 
36ca0 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74  collation X on t
36cb0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36cc0 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a  nection] B for.*
36cd0 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
36ce0 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f  ases having enco
36cf0 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ding E..**.** {H
36d00 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e  16604} SQLite un
36d10 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 58 20  derstands the X 
36d20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
36d30 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
36d40 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36d50 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
36d60 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65  D)] as a zero-te
36d70 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
36d80 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
36d90 67 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  g in which case 
36da0 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41  is ignored for A
36db0 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 20  SCII characters 
36dc0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
36dd0 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66  is significant f
36de0 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61  or non-ASCII cha
36df0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b  racters..**.** {
36e00 48 31 36 36 30 36 7d 20 53 75 63 63 65 73 73 69  H16606} Successi
36e10 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ve calls to [sql
36e20 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36e30 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
36e40 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
36e50 20 20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65     with the same
36e60 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58   values for B, X
36e70 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64  , and E, overrid
36e80 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a  e prior values.*
36e90 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c  *          of P,
36ea0 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a   F, and D..**.**
36eb0 20 7b 48 31 36 36 30 39 7d 20 49 66 20 74 68 65   {H16609} If the
36ec0 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e   destructor D in
36ed0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36ee0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
36ef0 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
36f00 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e          is not N
36f10 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63  ULL then it is c
36f20 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d  alled with argum
36f30 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a  ent P when the.*
36f40 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
36f50 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
36f60 20 64 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69   dropped by SQLi
36f70 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31  te..**.** {H1661
36f80 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  2} A collating f
36f90 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70  unction is dropp
36fa0 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76  ed when it is ov
36fb0 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  erloaded..**.** 
36fc0 7b 48 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61  {H16615} A colla
36fd0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
36fe0 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68   dropped when th
36ff0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
37000 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
37010 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e    is closed usin
37020 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
37030 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  ()]..**.** {H166
37040 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20  18} The pointer 
37050 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72  P in [sqlite3_cr
37060 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
37070 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a  2(B,X,E,P,F,D)].
37080 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70  **          is p
37090 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
370a0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
370b0 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70  eter to the comp
370c0 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
370d0 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f     function F fo
370e0 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  r all subsequent
370f0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
37100 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31  F..**.** {H16621
37110 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  } A call to [sql
37120 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37130 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29  ation(B,X,E,P,F)
37140 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20  ] is exactly.** 
37150 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
37160 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b  e as a call to [
37170 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37180 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77  ollation_v2()] w
37190 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
371a0 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74  the same paramet
371b0 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64  ers and a NULL d
371c0 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a  estructor..**.**
371d0 20 7b 48 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77   {H16624} Follow
371e0 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63  ing a [sqlite3_c
371f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
37200 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
37210 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  ,.**          SQ
37220 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 63 6f  Lite uses the co
37230 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
37240 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74  n F for all text
37250 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20   comparison.**  
37260 20 20 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f          operatio
37270 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ns on the [datab
37280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37290 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73  B on text values
372a0 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
372b0 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74    use the collat
372c0 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d  ing sequence nam
372d0 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ed X..**.** {H16
372e0 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  627} The [sqlite
372f0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37300 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d  on16(B,X,E,P,F)]
37310 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a   works the same.
37320 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 5b  **          as [
37330 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37340 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50  ollation(B,X,E,P
37350 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  ,F)] except that
37360 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
37370 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20   collation name 
37380 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20  X is understood 
37390 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
373a0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
373b0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 74 65  *          inste
373c0 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a  ad of UTF-8..**.
373d0 2a 2a 20 7b 48 31 36 36 33 30 7d 20 57 68 65 6e  ** {H16630} When
373e0 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72   multiple compar
373f0 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61  ison functions a
37400 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72  re available for
37410 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
37420 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
37430 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65  sequence, SQLite
37440 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65   chooses the one
37450 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f   whose text enco
37460 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
37470 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
37480 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  ast amount of co
37490 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68  nversion from th
374a0 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20  e default.**    
374b0 20 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64        text encod
374c0 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
374d0 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ase..*/.int sqli
374e0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
374f0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
37500 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
37510 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
37520 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
37530 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
37540 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
37550 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
37560 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
37570 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
37580 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
37590 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
375a0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
375b0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
375c0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
375d0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
375e0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
375f0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
37600 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
37610 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
37620 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
37630 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
37640 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
37650 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
37660 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
37670 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
37680 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
37690 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
376a0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
376b0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
376c0 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
376d0 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
376e0 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32  cks {H16700} <S2
376f0 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  0300>.**.** To a
37700 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
37710 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
37720 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
37730 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
37740 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
37750 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
37760 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
37770 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
37780 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
37790 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
377a0 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68   to be called wh
377b0 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
377c0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
377d0 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
377e0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  uired..**.** If 
377f0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
37800 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
37810 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
37820 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
37830 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
37840 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
37850 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
37860 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
37870 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
37880 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
37890 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66  F-8. {H16703} If
378a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
378b0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
378c0 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
378d0 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
378e0 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
378f0 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
37900 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c  order..** A call
37910 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
37920 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79  ion replaces any
37930 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61   existing callba
37940 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ck..**.** When t
37950 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
37960 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
37970 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
37980 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
37990 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
379a0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
379b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
379c0 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
379d0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
379e0 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
379f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
37a00 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
37a10 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
37a20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
37a30 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
37a40 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
37a50 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
37a60 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
37a70 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
37a80 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
37a90 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
37aa0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
37ab0 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
37ac0 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
37ad0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
37ae0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
37af0 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
37b00 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a  tion sequence..*
37b10 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
37b20 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
37b30 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
37b40 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
37b50 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
37b60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37b70 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
37b80 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37b90 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
37ba0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37bb0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
37bc0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
37bd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20  .**.** {H16702} 
37be0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
37bf0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
37c00 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44  llation_needed(D
37c10 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,P,F)].**       
37c20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
37c30 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
37c40 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73  6(D,P,F)] causes
37c50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
37c60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37c70 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f  ction] D to invo
37c80 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69  ke callback F wi
37c90 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  th first.**     
37ca0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 50       parameter P
37cb0 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65   whenever it nee
37cc0 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20  ds a comparison 
37cd0 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a  function for a.*
37ce0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
37cf0 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68  ting sequence th
37d00 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b  at it does not k
37d10 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a  now about..**.**
37d20 20 7b 48 31 36 37 30 34 7d 20 45 61 63 68 20 73   {H16704} Each s
37d30 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
37d40 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  o [sqlite3_colla
37d50 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f  tion_needed()] o
37d60 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
37d70 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37d80 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65  _needed16()] ove
37d90 72 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62  rrides the callb
37da0 61 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a  ack registered.*
37db0 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68  *          on th
37dc0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
37dd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20   connection] by 
37de0 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65  prior calls to e
37df0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
37e00 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a    interface..**.
37e10 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54 68 65 20  ** {H16706} The 
37e20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75  name of the requ
37e30 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20  ested collating 
37e40 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20  function passed 
37e50 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
37e60 20 20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72     4th parameter
37e70 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
37e80 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20   is in UTF-8 if 
37e90 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
37ea0 20 20 20 20 20 20 20 20 20 77 61 73 20 72 65 67           was reg
37eb0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73  istered using [s
37ec0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37ed0 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a  _needed()] and.*
37ee0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
37ef0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
37f00 79 74 65 20 6f 72 64 65 72 20 69 66 20 74 68 65  yte order if the
37f10 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a   callback was.**
37f20 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
37f30 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ered using [sqli
37f40 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37f50 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  eded16()]..*/.in
37f60 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
37f70 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
37f80 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
37f90 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
37fa0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
37fb0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
37fc0 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
37fd0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
37fe0 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
37ff0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
38000 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
38010 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
38020 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
38030 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  ).);../*.** Spec
38040 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
38050 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
38060 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
38070 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
38080 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
38090 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
380a0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
380b0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
380c0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
380d0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
380e0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
380f0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
38100 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
38110 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
38120 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
38130 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
38140 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
38150 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
38160 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
38170 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
38180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
38190 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
381a0 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
381b0 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
381c0 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
381d0 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
381e0 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
381f0 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
38200 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
38210 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
38220 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
38230 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
38240 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
38250 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
38260 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
38270 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
38280 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
38290 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
382a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
382b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
382c0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
382d0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
382e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
382f0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
38300 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
38310 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
38320 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65  REF: Suspend Exe
38330 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
38340 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d  rt Time {H10530}
38350 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S40410>.**.** 
38360 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
38370 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
38380 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
38390 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
383a0 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
383b0 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
383c0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
383d0 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
383e0 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
383f0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
38400 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
38410 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
38420 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
38430 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
38440 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
38450 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
38460 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
38470 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
38480 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
38490 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
384a0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
384b0 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
384c0 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
384d0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
384e0 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
384f0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
38500 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
38510 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
38520 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
38530 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
38540 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
38550 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
38560 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
38570 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54  **.** {H10533} T
38580 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
38590 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
385a0 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65  invokes the xSle
385b0 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ep.**          m
385c0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
385d0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
385e0 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20  s|VFS] in order 
385f0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  to.**          s
38600 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
38610 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
38620 74 68 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65  thread for at le
38630 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ast.**          
38640 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a  M milliseconds..
38650 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54  **.** {H10536} T
38660 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
38670 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
38680 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
38690 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
386a0 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f    milliseconds o
386b0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
386c0 20 72 65 71 75 65 73 74 65 64 20 6f 66 20 74 68   requested of th
386d0 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20  e operating.**  
386e0 20 20 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20          system, 
386f0 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c  which might be l
38700 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 70  arger than the p
38710 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69  arameter M..*/.i
38720 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
38730 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
38740 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
38750 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
38760 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
38770 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30  es {H10310} <S20
38780 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  000>.**.** If th
38790 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
387a0 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
387b0 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
387c0 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
387d0 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
387e0 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
387f0 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
38800 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
38810 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
38820 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  te will be place
38830 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
38840 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61  ory.  If this va
38850 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e  riable.** is a N
38860 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
38870 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d  n SQLite perform
38880 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61  s a search for a
38890 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
388a0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20   temporary file 
388b0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
388c0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
388d0 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  to modify this v
388e0 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 5b